Testing |
Anki add-on that uses LLMs like ChatGPT to turn your vocabulary flashcards into fresh sentences on the fly.
Anki is a great tool for learning vocabulary, but it's not great at teaching you how to use that vocabulary in a sentence. This matters, especially for languages like Ukrainian where each verb and noun can appear in many different forms! Phrasify uses an LLM like GPT 3.5/4 to generate sentences on the fly using your vocabulary. This way, you can practice using your vocabulary in a sentence and start using it in conversations.
For example, say I'm trying to learn the Ukrainian word "дарувати" (to give (a gift)) and I've added it to my deck. Phrasify generates a new relevant sentence every time I review the card:
Table of Contents
At the moment, Phrasify is not yet available on AnkiWeb. You can install it manually by following the instructions below.
Tools
> Phrasify - Set OpenAI API Key...
. Copy-paste your API key into the dialog that pops up and click Save
.Phrasify's automatic card generation can be enabled for a given note type by navigating to Tools
> Manage Note Types
> (Select your note type).
If you go to the Fields
button, you might see fields "Front" and "Back" like this:
Phrasify works using a field filter, by replacing the values in these fields with the generated
sentence. To do this, you need to tell Phrasify which fields to replace. Going back to
Tools
> Manage Note Types
> (Select your note type), click on the Cards
button.
In the Front Template
and Back Template
, replace the fields {{Front}}
with
{{phrasify vocab-to-sentence source_lang=English target_lang=Ukrainian source_field=Front target_field=Back:Front}}
and {{Back}}
with
{{phrasify vocab-to-sentence source_lang=English target_lang=Ukrainian source_field=Front target_field=Back:Back}}
For the default Basic card, the Front Template
would then look like this:
and the Back Template
would look like this:
This will tell Phrasify to replace the fields Front
and Back
with the generated sentence
at the spot in the template where {{phrasify ...:Front}}
and {{phrasify ...:Back}}
are.
Be sure to adjust the following arguments of the
{{phrasify...}}
filter to your needs:
source_lang
: source language, i.e. language that you know,target_lang
: target language, i.e. language that you want to learn,source_field
: field name for source language: stores the vocabulary in the language that you know,target_field
: field name for target language: stores the vocabulary in the language that you want to learn.
That's it! When you review a card with the note type you just edited, Phrasify will generate a sentence using the vocabulary on the card and replace the fields Front
and Back
with the generated sentence.
phrasify
is distributed under the terms of the MIT license.
First, clone the repository:
git clone https://github.com/mathijsvdv/phrasify.git
This repo uses Hatch for dependency management. I recommend
using pipx
to install it globally. To ensure that Visual Studio Code recognizes the virtual environment, set the virtual environment directory ./direnv:
hatch config set dirs.env.virtual .direnv
To set up the virtual environment along with pre-commit hooks and jupyter notebooks, run:
just init
To activate the virtual environment, run:
hatch shell
You will need to set up the OPENAI_API_KEY environment variable as described in the installation section.
In the directory src/phrasify/user_files
you need to create two files:
.env
with the following content:
OPENAI_API_KEY=your-api-key
INIT_PHRASIFY_ADDON=false
.env.prod
with the following content:
OPENAI_API_KEY=your-api-key
INIT_PHRASIFY_ADDON=true
The INIT_PHRASIFY_ADDON
environment variable is used to determine whether the field filters from the
add-on should be initialized. We want to disable this in the development environment where
the unit tests are run, but enable it when testing the add-on in Anki (i.e. when applying the current code to your Anki installation).
To run the tests, run:
hatch run test:run
Running the tests with code coverage can be done using:
hatch run test:cov
To apply the current development code to your Anki installation, run:
just ankidev
This copies the current code to your Anki add-ons folder. You can then restart Anki to see the changes.
Important for Linux and MacOS users: The
ankidev
rule (indirectly) makes use of theANKI_ADDONS_PATH
variable, defined inconfig-default.mk
. This variable is set to the default Anki add-ons folder on Windows with WSL. This means that theankidev
rule only works out of the box for Windows with WSL.For Linux and MacOS users, you need to override this by setting
ANKI_ADDONS_PATH
inconfig.mk
(which is gitignored) to the path of your Anki add-ons folder. You can find the folder by going toTools
>Add-ons
>View Files
in Anki. Place the following line inconfig.mk
(create it if it doesn't exist):ANKI_ADDONS_PATH = /path/to/your/anki/addons/folder
For debugging the add-on, it helps to have a console open which shows all logging and print output. See https://addon-docs.ankiweb.net/console-output.html#showing-the-console for more information.
The logging level can be set in the /src/phrasify/logging_config.json file. The default logging level is "INFO", but you can set it to "DEBUG" for more detailed logging and subsequently apply it to your Anki installation.
To build the add-on, run:
just build
This project uses the GitHub Flow branching strategy. No pushes to main
are allowed, only pull requests from feature branches that branch off of main
. Each feature branch has the following naming convention:
git branch <issue-id>-<description-in-kebab-case>
It's recommended to open an issue in GitHub before you create a feature branch so that you can more easily track the work and provide much more context.
Example:
git branch 123-cache-cards
is a feature branch implementing caching of cards, referring to Issue 123.