amirhossein-yousefi/swahili-biomed-adapters

# swahili-biomed-adapters MAD-X-style adapter stacking for cross-lingual domain adaptation in Swahili biomedical NLP. The pipeline trains a Swahili **language adapter (LA)** via MLM, an English **biomedical domain adapter (DA)** via MLM, and supervised **task adapters (TA)** for medical MCQA / NER / topic classification, then composes them at inference: `[LA_swh → DA_eng → TA]` on a frozen AfroXLMR-large backbone using the HuggingFace `adapters` library (Poth et al. 2023). See `compass_artifact_*.md` for the full project plan, literature review, and benchmark gap analysis. ## Quick start ```bash # 1. Environment — pick ONE # (a) uv (recommended; fast, locks Python version): curl -LsSf astral.sh | sh # one-time, installs to ~/.local/bin export PATH="$HOME/.local/bin:$PATH" uv venv --python 3.10 .venv source .venv/bin/activate uv pip install -e ".[dev]" # add ,flash on a CUDA-toolchain box # (b) plain pip: pip install -e .[flash,dev] # (c) conda: conda env create -f environment.yml # 2. Secrets (.env is gitignored; auto-loaded on `import multilingual`) # Searched in order: ./.env, src/multilingual/.env, $MULTILINGUAL_ENV_FILE cat > .env <<'EOF' HF_TOKEN=hf_xxx # mirrored to HUGGING_FACE_HUB_TOKEN automatically WANDB_API_KEY=xxx # optional RESULTS_DIR=./results # optional; defaults match these CKPT_DIR=./checkpoints DATA_DIR=./data EOF # 3. Sanity tests (must pass before any real training) make test # full suite — downloads xlm-roberta-base (~1.1GB) pytest -m "not heavy" # quick subset, no model download # 3. Data prep make data # download/clean/dedup/filter all corpora # 4. Train adapters (frozen backbone; only adapter params updated) make la # Swahili LA, MLM, ~1–2 days on DGX Spark make da # English biomedical DA, MLM, ~1–2 days make ta # M …