If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/LoRA shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 1y ago

• 13 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/LoRA repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/LoRA.

What it runs against: a local clone of microsoft/LoRA — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/LoRA | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 536 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/LoRA. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/LoRA.git
#   cd LoRA
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/LoRA and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/LoRA(\\.git)?\\b" \\
  && ok "origin remote is microsoft/LoRA" \\
  || miss "origin remote is not microsoft/LoRA (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 536 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~506d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/LoRA"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

loralib is a PyTorch implementation of Low-Rank Adaptation (LoRA), a parameter-efficient fine-tuning technique that reduces trainable parameters by 99%+ (e.g., 125M → 0.8M on RoBERTa base) by learning low-rank decomposition matrices while freezing original weights. It enables efficient task-switching and model adaptation without introducing inference latency, achieving comparable or superior results to full fine-tuning on GLUE benchmarks. Two-part structure: (1) loralib/ (inferred as main package, not visible in file tree but referenced in README) contains the core LoRA layer implementations; (2) examples/ splits into examples/NLG/ (GPT-2 fine-tuning on DART, E2E, WebNLG with src/ containing data_utils.py, gpt2_ft.py, model.py) and examples/NLU/ (GLUE tasks with RoBERTa/DeBERTa). Datasets are committed in examples/NLG/data/.

ML engineers and researchers fine-tuning large language models (LLMs) who need to adapt models to specific tasks with minimal storage overhead and no inference slowdown. Users include practitioners working with Hugging Face transformers, RoBERTa, DeBERTa, and GPT-2/GPT-3 scale models who want parameter-efficient alternatives to full fine-tuning.

Production-ready and actively maintained by Microsoft Research. The codebase is ~15K lines of Python with concrete examples for NLG (e.g., examples/NLG/ with DART, E2E, WebNLG datasets) and NLU tasks. LoRA is now officially supported by Hugging Face's PEFT library (as of 2/2023), indicating mature adoption. Paper published (arxiv.org/abs/2106.09685) with published checkpoints for RoBERTa and DeBERTa.

Low risk for a research-backed library. Dependencies are minimal (PyTorch only, no external build chains). The core loralib package appears lightweight with clear integration points. Main risk: this is a reference implementation that saw its primary use case superseded by the HuggingFace PEFT library (2023), so the repo may receive fewer updates than before, though the core LoRA algorithm is stable and well-validated.

The repo is in maintenance mode post-PEFT integration (2/2023). Most active development likely shifted to HuggingFace/peft. The examples/ directory contains runnable training scripts (gpt2_ft.py) and evaluation code (eval/eval.py), suggesting the repo is actively used for benchmarking and as a reference implementation rather than new feature development.

git clone https://github.com/microsoft/LoRA.git
cd LoRA
# Install from PyPI (LoRA now in transformers/PEFT) or dev install:
pip install -e .
# For NLG examples: cd examples/NLG && pip install -r requirement.txt
# For NLU: cd examples/NLU && make install (implied from Makefile)

Daily commands: For NLG (GPT-2 fine-tuning on DART): cd examples/NLG && python src/gpt2_ft.py (see gpt2_ft.py for full CLI args; requires vocab/ and data/dart/). For NLU (GLUE with RoBERTa/DeBERTa): exact commands in examples/NLU/Makefile (structure suggests make finetune or similar). Evaluation: examples/NLG/eval/eval.py for NLG metrics (BLEU, ROUGE, METEOR).

• examples/NLG/src/gpt2_ft.py: Core fine-tuning training loop for GPT-2 with LoRA; demonstrates how to integrate LoRA into a transformer model and train with low-rank adapters.
• examples/NLG/src/model.py: Model architecture wrapper showing how to apply LoRA layers to a base GPT-2 model (likely calls loralib functions to replace Linear layers).
• examples/NLG/src/data_utils.py: Dataset loading and preprocessing for DART, E2E, and WebNLG; essential for understanding input pipeline and data format expectations.
• examples/NLG/eval/eval.py: Evaluation harness for NLG tasks; computes BLEU, ROUGE, and METEOR metrics used to validate fine-tuned models.
• examples/NLU/Makefile: Orchestrates NLU (GLUE) training and evaluation; defines targets for fine-tuning RoBERTa and DeBERTa with LoRA on NLU benchmarks.
• README.md: Contains paper reference, benchmark results table (RoBERTa/DeBERTa GLUE scores), and links to downloadable LoRA checkpoints.

To add LoRA to a new model: extend loralib (core package, not visible in tree but likely loralib/.py) with LoRA-compatible layer types (analog to LoRA.Linear, LoRA.Conv2d). To add datasets: place data in examples/{NLG,NLU}/data/ and add corresponding format_converting_.py in examples/NLG/src/. To add training runs: extend gpt2_ft.py or create new task-specific training script in examples/{NLG,NLU}/src/. To benchmark: use examples/NLG/eval/ or examples/NLU/ evaluation utilities.

No explicit setup.py or pyproject.toml in visible files: the package name 'loralib' is referenced but the core module directory is not shown; likely in a top-level loralib/ folder not listed. Dataset dependencies: examples/NLG/data/ includes pre-downloaded DART/E2E/WebNLG files; examples/NLU likely expects HuggingFace GLUE auto-download (requires internet on first run). Vocab files: examples/NLG/vocab/ must be present; gpt2_encode.py / gpt2_decode.py depend on vocab.json, encoder.json, and tokenizer.json being available. No explicit GPU requirement stated: code likely requires CUDA for practical training; CPU-only will be slow. PEFT supersession: this repo is now primarily a reference; for production use, integrate LoRA via transformers.integrations.peft or peft library directly.

• Low-Rank Decomposition (Matrix Factorization) — LoRA's core mechanism: instead of fine-tuning a weight matrix W ∈ ℝ^(d_out × d_in), it learns two smaller matrices A ∈ ℝ^(d_out × r) and B ∈ ℝ^(r × d_in) where r << min(d_out, d_in); understanding rank selection (e.g., r=8) is critical for tuning accuracy vs. parameter efficiency.
• Parameter-Efficient Fine-Tuning (PEFT) — LoRA is one strategy in the broader PEFT family (adapters, prefix-tuning, prompt tuning); understanding the landscape helps you choose when LoRA is appropriate (e.g., LoRA > adapters for inference latency, LoRA ≈ full fine-tuning for quality).
• Rank (Tensor Algebra) — The hyperparameter r (rank of LoRA matrices) directly controls the capacity and parameter count; a rank of 8 on a 768D layer gives 0.8M params vs. 125M for full fine-tuning on RoBERTa; understanding rank-parameter tradeoffs is essential for deployment decisions.
• Adapter Layers & Module Composition — LoRA layers replace frozen Linear layers in transformers using PyTorch's nn.Module composition pattern; understanding how to surgically insert LoRA into a pre-trained model (e.g., in attention/feed-forward layers but not embeddings) is key to correct implementation.
• Checkpoint Serialization & State Dicts — LoRA checkpoints are tiny (~0.8M params) compared to full models, enabling efficient storage and task-switching; understanding PyTorch state_dict filtering (saving only LoRA weights, not frozen base weights) is critical for deployment and checkpoint management.
• Inference Latency & Hardware Efficiency — LoRA has zero inference overhead: at inference time, the learned low-rank product BA is fused into the base weight matrix W or computed on-the-fly with negligible cost; this contrasts with adapter layers which add sequential computation; understanding this property justifies LoRA for production deployment.
• BLEU, ROUGE, METEOR (NLG Metrics) — examples/NLG/eval/eval.py computes these metrics to benchmark fine-tuned GPT-2 models on DART, E2E, WebNLG; these metrics measure n-gram overlap and semantic similarity; understanding their limitations (e.g., BLEU can disagree with human judgment) is important for interpreting results.

• huggingface/peft — Official successor: HuggingFace's Parameter-Efficient Fine-Tuning library that now includes LoRA as a first-class citizen alongside adapters and prefix-tuning; this repo is the reference implementation PEFT builds on.
• microsoft/DeepSpeed — Complementary efficiency library by Microsoft for distributed training; often used alongside LoRA to further reduce memory and accelerate training on multi-GPU setups.
• allenai/allennlp — NLP research framework that provides GLUE task pipelines and evaluation utilities similar to examples/NLU structure; useful for understanding how to structure multi-task fine-tuning experiments.
• huggingface/transformers — Core dependency: loralib integrates directly with HF Transformers models (RoBERTa, DeBERTa, GPT-2); LoRA is now built-in via PEFT integration in transformers.
• nyu-dl/FastFormers — Earlier parameter-efficient fine-tuning approach (adapters, distillation); LoRA paper and this repo position LoRA as a superior alternative with better accuracy/parameter tradeoff.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for loralib core modules

The repo has examples in examples/NLG/src and examples/NLU but no visible test suite for the core loralib package itself. There are no test files (.py test files or pytest configuration) at the root level. This is critical for a library that users depend on, as it ensures LoRA layer implementations work correctly across different model architectures and PyTorch versions.

• [ ] Create tests/ directory at repository root
• [ ] Add unit tests for LoRA layer implementations (test different rank values, in_features/out_features combinations)
• [ ] Add integration tests for common model types (test with HuggingFace transformer models like RoBERTa, GPT-2)
• [ ] Create pytest.ini or setup.cfg with test configuration
• [ ] Add test cases validating gradient flow and parameter freezing behavior
• [ ] Document test running instructions in README.md

Add GitHub Actions CI workflow for testing and compatibility validation

The repo has no visible CI configuration (.github/workflows directory is missing). Given that this is a PyTorch library used across multiple model types (NLG examples with GPT-2, NLU examples with RoBERTa/DeBERTa), automated testing across Python versions and PyTorch versions would catch regressions and compatibility issues early.

• [ ] Create .github/workflows/tests.yml workflow
• [ ] Configure matrix testing for Python 3.8, 3.9, 3.10, 3.11
• [ ] Configure matrix testing for PyTorch LTS and latest versions
• [ ] Add lint checks (flake8 or ruff) for code quality
• [ ] Verify tests pass on both CPU and GPU (or at least CPU for CI)
• [ ] Add status badge to README.md

Create comprehensive API documentation for loralib core functions

While examples/NLG and examples/NLU demonstrate usage, there's no dedicated API documentation file explaining the core loralib classes and functions (LoRALinear, LoRAMergedLinear, etc.). The README is truncated and doesn't detail the main API. New users need clear documentation of what functions are available, parameters, return types, and usage patterns.

• [ ] Create docs/API.md documenting all public classes and functions in loralib
• [ ] Add docstring examples showing how to wrap a standard Linear layer with LoRA
• [ ] Document configuration parameters (r, lora_alpha, lora_dropout, target_modules)
• [ ] Add section on merging LoRA weights back into original model with merge_lora()
• [ ] Include example code snippets for common use cases (fine-tuning, inference)
• [ ] Link API documentation from main README.md

• Add unit tests for LoRA layer implementations: create tests/test_lora_layers.py to verify that LoRA.Linear and LoRA.Conv2d produce correct rank-decomposed gradients and weight updates; currently no tests/ directory is visible.
• Document API for loralib module: write docstrings and examples for how to import and use LoRA layers (e.g., from loralib import Linear and wrap pretrained weights); create examples/minimal_lora_example.py showing a 20-line example.
• Add support for new NLG dataset (e.g., XSUM, CNN/DailyMail): create examples/NLG/src/format_converting_xsum.py following the pattern of format_converting_dart.py, add dataset to examples/NLG/data/xsum/, and update README with new benchmark row.

The LoRA codebase demonstrates moderate security posture. No critical vulnerabilities were identified based on file structure analysis. However, the presence of shell scripts that download and execute external resources, untrusted data files embedded in the repository, unverified Docker configurations, and incomplete dependency visibility represent medium-low risk areas. The main concerns are: (1) potential command injection through shell scripts that download external resources, (2) unsafe handling of committed JSON data files without validation, (3) Docker security hardening practices not verified, and (4) inability to assess transitive dependency vulnerabilities. The repository follows good practice by maintaining a SECURITY.md file for Microsoft's vulnerability reporting process. Recommended actions include dependency vulnerability scanning, validation of data file handling, review of shell scripts for injection risks, and Docker security hardening.

• Medium · Shell Script Execution Without Input Validation — examples/NLG/create_datasets.sh, examples/NLG/download_pretrained_checkpoints.sh, examples/NLG/eval/download_evalscript.sh. Multiple shell scripts (create_datasets.sh, download_pretrained_checkpoints.sh, download_evalscript.sh) are present in the examples directory. Without visibility into their contents, these scripts may execute arbitrary commands or download untrusted resources. Shell scripts are particularly vulnerable to command injection if they process user input unsafely. Fix: Review all shell scripts for unsafe command constructions. Validate and sanitize any user inputs. Use absolute paths and explicit command references. Consider replacing shell scripts with Python equivalents for better control and security.
• Medium · Untrusted Data Files in Repository — examples/NLG/data/dart/*.json, examples/NLG/data/webnlg_challenge_2017/*.json. The repository contains multiple JSON data files (dart-v1.1.1-full-*.json, test.json, train.json, dev.json) that are committed to the repository. If these files are parsed without proper validation, they could be exploited for deserialization attacks or contain malicious training data that affects model behavior. Fix: Validate JSON schema before parsing. Use safe JSON parsers. Consider storing large data files outside the repository using versioned data management systems. Document the provenance and integrity of data files.
• Low · Missing Dependency File — examples/NLG/requirement.txt (and any root-level setup.py, pyproject.toml, or requirements.txt). The security analysis was unable to examine the package dependencies (requirements.txt or setup.py) as no dependency file content was provided. This prevents comprehensive assessment of transitive dependency vulnerabilities. Fix: Review and provide the complete dependency files. Regularly audit dependencies using tools like pip-audit or safety. Pin dependency versions and use hash verification. Monitor CVE databases for vulnerabilities in dependencies.
• Low · Docker Configuration Exposure — examples/NLU/docker/*/Dockerfile. Multiple Dockerfile configurations are present in the examples/NLU/docker directory. Without viewing the contents, potential security issues could include: running containers as root, not using specific base image tags, missing security scanning, or exposing unnecessary ports. Fix: Use specific tags for base images (avoid 'latest'). Run containers with non-root users. Implement Docker security scanning. Use multi-stage builds. Apply principle of least privilege for file permissions and exposed ports.
• Low · Incomplete Security Documentation — SECURITY.md, examples/NLG/SECURITY.md, examples/NLU/SECURITY.md. The SECURITY.md file appears to be truncated (ends with '...please report them to the Microsoft Security Response Center (MSRC) at https://msrc.microsoft.com/create-report. This incomplete security policy may not adequately inform users about vulnerability reporting procedures. Fix: Complete the SECURITY.md documentation with full vulnerability reporting guidelines. Include supported versions, response timelines, and PGP key information if applicable.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.