Mink Backend

Mink is Språkbanken's data platform. Its goal is to make our research infrastructure easily accessible to researchers. As a user, you can apply advanced language technology methods to your own data, and download or explore the results in our research tools with secure access.

Mink currently supports three kinds of resources:

• Corpora: have large text data annotated with Sparv, and explore it in Korp and Strix
• Lexicons: explore lists or tabular data in Karp's search mode and Karp's edit mode
• Metadata: add language resources to Språkbanken's resource catalogue

The Mink backend is a FastAPI application serving as a backend to the Mink frontend.

The source code is available under the MIT license. If you have any questions, problems or suggestions please contact sb-mink@svenska.gu.se.

Prerequisites

• Python 3.11 or newer
• memcached

Installation

To install the dependencies, we recommend using uv.

1. Install uv if you don't have it already.

2. While in the mink-backend directory, run:

   uv sync

   This will create a virtual environment in the .venv directory and install the dependencies listed in pyproject.toml and pinned in uv.lock.

Alternatively, you can set up a virtual environment manually using Python's built-in venv module and install the dependencies using pip:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

The pip install -e . path is convenient for local development, but it does not use uv.lock. For production, prefer rebuilding the virtual environment from the lockfile with uv sync --frozen.

How to Run a Development Server

default when running uv sync, unless --no-dev is specified). Start the development server (with and activated venv, alternatively with the uv run prefix, but then you can drop the python from the commands) with:

Ensure the dependencies listed in the [dev] section of pyproject.toml are installed. These are included by default when running uv sync, unless you specify --no-dev.

To start the development server (with an activated virtual environment or with the uv run prefix, dropping python from the commands), run:

python run.py [--host <host>] [--port <port>]

To start the queue manager, run:

python queue_manager.py

Once started, your development server will be running and you can access the API documentation at: http://localhost:8000/docs

How to Run in Production

Install production dependencies with the server extra:

uv sync --frozen --no-dev --extra server

For production, run Mink behind Gunicorn and use Uvicorn's worker class:

.venv/bin/gunicorn mink.main:app \
  --worker-class uvicorn_worker.UvicornWorker \
  --bind 127.0.0.1:9001 \
  --workers 1 \
  --forwarded-allow-ips="*"

Recommended production notes:

• Run the queue manager as a separate process:

  .venv/bin/python queue_manager.py

• If Mink is served from a URL prefix such as /mink, set ROOT_PATH=/mink in the app environment.

• When using uvicorn_worker.UvicornWorker, do not rely on Gunicorn's --root-path flag; configure ROOT_PATH in Mink instead.

• Set MINK_URL to the complete URL where Mink is served (e.g. https://example.com/mink) to ensure correct URL generation in the API responses.

Configuration

The default core configuration is defined in mink/core/config.py and module-specific settings live in their respective packages (e.g. mink/sparv/config.py, mink/metadata/config.py). Use the config_helper.py script to print the current configuration values for all modules:

python config_helper.py

To override the default settings, create a .env file in the project's root directory and set the environment variables listed in config.py. For examples, see the developer's guide.

Tracking to Matomo

To enable tracking to Matomo, set the following config variables:

• TRACKING_MATOMO_URL - url to matomo
• TRACKING_MATOMO_IDSITE - id for this site (get from matomo admin)
• TRACKING_MATOMO_AUTH_TOKEN - access token to enable tracking IP numbers

Testing

To run the automated tests, use pytest (with an activated virtual environment, or prefix the command with uv run):

pytest [--custom-log-level=<log_level>] [--mink-log-level=<log_level>] [-k <test_name>]