Phrasify

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

• Installation
• Try it out!
• License
• Development
  • Setting up the development environment
  • Running tests
  • Applying the current code to your Anki installation
  • Debugging the add-on
  • Building the add-on
  • Branching strategy

Installation

At the moment, Phrasify is not yet available on AnkiWeb. You can install it manually by following the instructions below.

1. Download the latest release from the releases page. If you already have Anki installed, you can double-click the .ankiaddon file to install the addon.
2. Restart Anki. Phrasify will warn you in case you haven't set up your OpenAI API key yet, in which case, go to step 3.
3. Phrasify makes use of the OpenAI API to generate sentences. We need to set up the API key in order to use the add-on. To do this, follow these steps:
   1. Sign up for an API key at OpenAI if you haven't already.
   2. Once you have your API key, open Anki and go to Tools > Phrasify - Set OpenAI API Key.... Copy-paste your API key into the dialog that pops up and click Save.
4. That's it! You're ready to start using Phrasify.

Try it out!

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.

License

phrasify is distributed under the terms of the MIT license.

Development

Setting up the development environment

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

Running tests

To run the tests, run:

hatch run test:run

Running the tests with code coverage can be done using:

hatch run test:cov

Applying the current code to your Anki installation

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 the ANKI_ADDONS_PATH variable, defined in config-default.mk. This variable is set to the default Anki add-ons folder on Windows with WSL. This means that the ankidev 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 in config.mk (which is gitignored) to the path of your Anki add-ons folder. You can find the folder by going to Tools > Add-ons > View Files in Anki. Place the following line in config.mk (create it if it doesn't exist):

ANKI_ADDONS_PATH = /path/to/your/anki/addons/folder

Debugging the add-on

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.

Building the add-on

To build the add-on, run:

just build

Branching strategy

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.