kotobuki is a Python package that can update custom mappings created in Usagi that have become outdated in a new release of the OHDSI vocabularies.

kotobuki requires Python 3.11+ and is available on PyPI.

Depending on the type of database you have, you'll also need to install the required python adapter library. E.g. for postgresql, you can use psycopg2.

See SQLAlchemy docs for a list of supported dialects.

As kotobuki is intended to be used as a standalone tool, the recommended method of installation is in an isolated (temporary) environment.

E.g. if using uv with a postgresql database:

uvx --with psycopg2 --from kotobuki update-usagi-file --help

Or within a Jupyter notebook:

uv run --with jupyter,psycopg2,kotobuki jupyter lab

See User documentation

Make sure the following tooling is installed:

• uv

Install the project and dev dependencies via uv sync --all-groups.

Then set up the git hook scripts via uv run pre-commit install.

Run nox -l for a list of available nox sessions, or simply run nox to run the ruff linter and the pytest suite for all supported Python versions.