Installation & requirements

The project can be reproduced in two ways:

  • the Docker service, which is the recommended path for running the web application and API;

  • a local Python environment, which is useful for training, debugging, and running scripts outside the container.

Repository layout

The main runtime files are:

  • demo_n_api/docker-compose.yml: starts the Flask app, MySQL, and Caddy.

  • demo_n_api/app/Dockerfile: builds the Flask application image.

  • demo_n_api/app/requirements.txt: Python dependencies for the application.

  • demo_n_api/app/app.py: Flask routes, authentication, translation, scoring, and suggestion storage.

  • demo_n_api/app/translate/translate.py: NLLB model loading and inference.

  • demo_n_api/db/init.sql: database schema and initial user rows.

  • demo_n_api/db/terminology_terms_table.csv: terminology table loaded by the service when available.

  • demo_n_api/Caddyfile: HTTPS and mTLS reverse-proxy configuration.

Docker requirements

Install the following before running the service:

  • Docker Engine or Docker Desktop with the Compose v2 plugin.

  • At least 8 GB RAM for CPU inference with the distilled NLLB model; more is recommended when the similarity model or LLM features are enabled.

  • A trained NLLB checkpoint directory available on the host machine.

  • Network access during the first build so Python packages and model/tokenizer assets can be downloaded.

  • For public HTTPS/mTLS deployment: a DNS name, a valid ACME email address, and a certificate authority file for client-certificate verification.

The Docker image uses python:3.9 because that is the runtime configured in demo_n_api/app/Dockerfile. Keep the container Python version aligned with demo_n_api/app/requirements.txt unless all pinned packages have been tested with a newer Python version.

Runtime directories

Create the expected host directories:

cd demo_n_api
New-Item -ItemType Directory -Force -Path models,credentials,mtls

The service expects the trained model to be mounted into the app container under /app/models. For a local reproduction, the Compose volume can be:

volumes:
  - ./models:/app/models
  - ./app:/app
  - ./.env:/app/.env:ro
  - ./db:/app/db:ro
  - ./credentials:/app/credentials:ro

The default model paths used by the app are configured with:

NLLB_MODEL_EN_FR=/app/models/checkpoint-16539
NLLB_MODEL_FR_EN=/app/models/checkpoint-16539

Environment file

Create demo_n_api/.env before starting Docker Compose. The file controls authentication, model paths, terminology loading, LLM options, and Caddy.

Minimal local API-key configuration:

API_AUTH_MODE=api_key
API_KEY=replace-with-local-development-key
APP_HOST=localhost
ACME_EMAIL=admin@example.org
TERMINOLOGY_TABLE_NAME=terminology_terms_table
TERMINOLOGY_CSV_PATH=/app/db/terminology_terms_table.csv
NLLB_MODEL_EN_FR=/app/models/checkpoint-16539
NLLB_MODEL_FR_EN=/app/models/checkpoint-16539
SENSITIVE_ENTITY_SCORE_THRESHOLD=0.9
SENSITIVE_ENTITY_TYPES=PERSON,PHONE_NUMBER,EMAIL_ADDRESS,CREDIT_CARD,IBAN_CODE,IP_ADDRESS,US_SSN,US_PASSPORT,US_DRIVER_LICENSE,US_BANK_NUMBER,CRYPTO

Optional LLM and similarity settings:

DEFAULT_LLM_PROVIDER=gemini
GEMINI_PROJECT_ID=
GEMINI_LOCATION=us-central1
GEMINI_MODEL=gemini-2.5-flash
OPENAI_API_KEY=
OPENAI_LLM_MODEL=
SIMILARITY_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

For mTLS deployment, also set:

API_AUTH_MODE=mtls
MTLS_CA_FILE=/etc/caddy/mtls/ca.crt
MTLS_CLIENT_FINGERPRINT_HEADER=X-Client-Cert-Fingerprint
MTLS_CLIENT_SUBJECT_HEADER=X-Client-Cert-Subject
MTLS_REQUIRE_FINGERPRINT_ALLOWLIST=false
MTLS_ALLOWED_FINGERPRINTS=

Do not commit real API keys, cloud service account JSON, private keys, or client certificate fingerprints.

Running with Docker

For local development without Caddy, publish the Flask app port in the app service:

ports:
  - "8080:8080"

Start the app and database:

docker compose up --build app db

For the full HTTPS/mTLS stack, keep the Caddy service enabled and start all services:

docker compose up --build

Check container status:

docker compose ps

Local Python environment

Use a virtual environment when running scripts or the Flask app outside Docker:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r demo_n_api/app/requirements.txt

Quick dependency checks:

python -c "from flask import Flask; print('Flask OK')"
python -c "from transformers import AutoTokenizer; AutoTokenizer.from_pretrained('facebook/nllb-200-distilled-600M'); print('NLLB tokenizer OK')"
python -c "from sentence_transformers import SentenceTransformer; print('SentenceTransformers OK')"

Training requirements

Training or fine-tuning NLLB is separate from serving the API. Recommended training requirements are:

  • Python 3.10 or newer in a separate training environment.

  • PyTorch with CUDA support.

  • An NVIDIA GPU with enough VRAM for the selected NLLB model.

  • transformers, datasets, evaluate, sentencepiece, sacrebleu, and accelerate.

  • For older preprocessing and binarization workflows: fairseq, Moses tokenizer scripts, and subword-nmt.

Core training dependencies:

pip install torch transformers datasets evaluate sentencepiece sacrebleu accelerate

Optional preprocessing tools:

pip install fairseq
git clone https://github.com/moses-smt/mosesdecoder
git clone https://github.com/rsennrich/subword-nmt

For large datasets, pyarrow is recommended:

pip install pyarrow

Documentation build

The HTML documentation is generated from demo_n_api/app/docs/_sources. Rebuild it after editing documentation sources:

cd demo_n_api/app/docs
./build_docs.ps1

The generated entry point is:

demo_n_api/app/docs/index.html

Installation checklist

Before using the service, verify that:

  • docker compose ps shows the expected services running.

  • /app/models inside the app container contains the configured checkpoint.

  • demo_n_api/.env contains the selected authentication mode and model paths.

  • MySQL has initialized the ans database.

  • TERMINOLOGY_CSV_PATH points to an accessible CSV when terminology highlighting is required.

  • /translate returns HTTP 200 for a valid test request.