AdapterBridge
LoRA Checkpoint & Config Compatibility Engine for Enterprise Inference Runtimes
AdapterBridge is an open-source pre-flight compatibility, validation, and remediation engine that eliminates runtime deployment failures when moving fine-tuned Low-Rank Adaptation (LoRA/QLoRA) checkpoints into production inference runtimes (vLLM, SGLang, Ollama, TensorRT-LLM).
Executive Summary & Case Study
1. Problem Statement
Post-training frameworks (Unsloth, Axolotl, LLaMA-Factory, Hugging Face PEFT) make fine-tuning open-weight foundation models (Llama 3.x, Qwen 2.5, Mistral, DeepSeek) accessible. However, exported checkpoint directories are frequently incompatible with production serving runtimes without manual intervention.
Incompatibilities are typically discovered only after a deployment has already consumed compute resources:
| Failure Mode | Root Cause | Downstream Impact |
|---|---|---|
| Missing Config Files | Training exports include adapter_model.safetensors + adapter_config.json only, omitting config.json or tokenizer bundles. |
Serving engine process crashes at startup before accepting requests. |
| State-Dict Key Drift | Inconsistent framework prefixes (base_model.model.model.layers.0... vs. model.layers.0...). |
Weight loading fails or silently drops layers. |
| Malformed Chat Templates | Custom Jinja2 chat templates with syntax errors or unhandled message roles. | OpenAI-compatible /v1/chat/completions endpoint fails during request processing. |
| Dimension & Rank Mismatch | lora_alpha/r or target_modules do not align with tensor parallelism sharding expectations. |
Matrix shape errors at load time across multi-GPU clusters. |
2. Operational Cost & Pre-Flight Mitigation
In distributed inference environments (Kubernetes, Ray, Slurm), catching configuration mismatches at load time wastes compute budget and delays deployment pipelines.
Traditional Workflow (Late Failure):
Training Export -> CI/CD Deploy -> GPU Pod Scheduled -> Weights Load -> Load Error (High GPU Cost)
AdapterBridge Workflow (Pre-Flight Gateway):
Training Export -> AdapterBridge Check (CPU, <2s) -> Validation & Remediation -> Clean Deployment (Zero GPU Cost)
AdapterBridge operates as a pre-flight validation gateway: static schema inspection, automated metadata synthesis, zero-copy binary streaming tensor key normalization, and CPU-only dry-run simulation before weights reach host VRAM or GPU pods.
System Architecture
+-------------------------------------------------------------+
| Presentation & Ingestion Layer |
| CLI (Typer + Rich) | Python SDK | CI/CD Integrations |
+-------------------------------+-----------------------------+
|
v
+-------------------------------------------------------------+
| AdapterBridge Core Engine |
| +---------------+ +---------------+ +-------------------+ |
| | Metadata | | Tensor & | | Chat Template | |
| | Scanner / | | Weight | | Linter & Sandbox | |
| | Lineage Engine| | Remapper | | (Sandboxed Jinja2)| |
| +---------------+ +---------------+ +-------------------+ |
| +-------------------------------------------------------+ |
| | Mock Serving Dry-Run Harness (PyTorch Meta/NumPy) | |
| +-------------------------------------------------------+ |
+-------------------------------+-----------------------------+
|
v
+-------------------------------------------------------------+
| Target Engine Profiles |
| vLLM | SGLang | Ollama | TensorRT-LLM | (Pluggable)|
+-------------------------------------------------------------+
Core Design Guarantees
- Zero-GPU Pre-Flight Verification: Every command (
check,fix,verify) executes on standard CPUs, local workstations, and CI runners. - Lazy Memory Inspection: Uses memory-mapped header parsing (
safetensors.safe_open) to inspect tensor headers, shapes, and dtypes without loading weight buffers into RAM. - Zero-Copy Binary Remapping: Re-serializes header offsets and streams raw byte buffers directly on disk without converting float arrays into Python memory.
- Atomic Staging Writes: File modifications execute in temporary staging directories (
.adapterbridge_staging_<uuid>) and atomically rename into place only after validation succeeds. - Sandboxed Template Evaluation: Jinja2 chat templates evaluate inside
jinja2.sandbox.SandboxedEnvironmentwith subprocess execution timeouts.
Core Capabilities (The 4 Verbs)
+------------------+
| Input Checkpoint |
+--------+---------+
|
+---------------------+---------------------+---------------------+
| | | |
v v v v
+---------+ +---------+ +----------+ +----------+
| CHECK | | FIX | | VERIFY | | EXPORT |
+---------+ +---------+ +----------+ +----------+
Static Linter Auto-Remapper Zero-GPU Dry-Run Target Bundler
& Validator & Synthesizer Memory Simulator & Exporter
1. adapterbridge check
Static schema inspection and linting against target serving engine rules (vLLM, SGLang, Ollama, TensorRT-LLM). Supports text table, JSON, SARIF, Markdown, and PR comment formats.
2. adapterbridge fix
Automated metadata synthesis and zero-copy key normalization. Resolves base model lineage from Hugging Face Hub with local disk caching (~/.cache/adapterbridge/hub/) and injects canonical, architecture-matched chat templates.
3. adapterbridge verify
Zero-GPU mock dry-run engine simulating layer allocation, matrix scaling (scale = alpha / r), and Tensor Parallelism (TP) sharding division using PyTorch meta device tensors (torch.empty(..., device="meta")) or NumPy shape math.
4. adapterbridge export
Bundles a verified checkpoint into target runtime directory layouts.
Installation
Standard CPU Installation
pip install adapterbridge
Installation with PyTorch Meta-Tensor Support
pip install adapterbridge[verify]
Development Installation
git clone https://github.com/adapterbridge/adapterbridge.git
cd AdapterBridge
pip install -e .[dev,verify]
Usage Scenarios
Scenario 1: CLI Inspection and Auto-Repair
1. Static Linter Check
adapterbridge check --path ./checkpoint-500 --target vllm
2. Auto-Repair Checkpoint
adapterbridge fix \
--src ./checkpoint-500 \
--dst ./checkpoint-500-repaired \
--target vllm \
--base-model meta-llama/Llama-3.1-8B-Instruct
3. Verify Repaired Checkpoint
adapterbridge check --path ./checkpoint-500-repaired --target vllm
4. Dry-Run Verification for Tensor Parallelism
adapterbridge verify --path ./checkpoint-500-repaired --target vllm --tensor-parallel-size 4
Scenario 2: GitHub Actions CI/CD Integration
Add .github/workflows/adapterbridge.yml to your repository:
name: Adapter Pre-Flight Check
on:
pull_request:
paths:
- 'checkpoints/**'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run AdapterBridge Check
uses: adapterbridge/adapterbridge/.github/actions/adapterbridge-check@main
with:
path: './checkpoints/adapter-latest'
target: 'vllm'
format: 'sarif'
output: 'adapterbridge.sarif'
- name: Upload Security & Compliance SARIF Report
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: 'adapterbridge.sarif'
Scenario 3: Local Pre-Commit Hook Integration
Add to .pre-commit-config.yaml:
repos:
- repo: https://github.com/adapterbridge/adapterbridge
rev: v0.1.1
hooks:
- id: adapterbridge-check
args: ["--path", "./checkpoints/my-adapter", "--target", "vllm"]
Scenario 4: Containerized Execution (Docker)
Run inside Kubernetes admission gates or MLOps pipelines:
docker run --rm -v $(pwd)/checkpoint:/workspace/checkpoint \
ghcr.io/adapterbridge/adapterbridge:latest check --path /workspace/checkpoint --target vllm
Python SDK Reference
from adapterbridge import AdapterInspector, TargetEngine
# Initialize inspector
inspector = AdapterInspector(
checkpoint_path="./checkpoints/my-adapter",
target_engine=TargetEngine.VLLM,
)
# Inspect Checkpoint Manifest
manifest = inspector.manifest
print(f"Base model ID: {manifest.base_model_id}")
print(f"Rank r: {manifest.lora_r}, Alpha: {manifest.lora_alpha}")
# Run Diagnostics
report = inspector.run_diagnostics()
if not report.is_compatible:
print(f"Validation failed with {len(report.errors)} error(s). Executing auto-repair...")
# Auto-repair checkpoint
plan = inspector.auto_repair(
destination_path="./checkpoints/my-adapter-production",
fallback_base_model="meta-llama/Llama-3.1-8B-Instruct",
)
print(f"Repaired output path: {plan.output_path}")
# Run Dry-Run Verification
verification = inspector.verify_dry_run(tensor_parallel_size=2)
print(f"Dry-run status: {verification.success}")
print(f"Estimated RAM footprint: {verification.memory_estimate_mb} MB")
Target Engine Specification Matrix
| Feature / Requirement | vLLM (vllm) |
SGLang (sglang) |
Ollama (ollama) |
TensorRT-LLM (tensorrt) |
|---|---|---|---|---|
config.json |
Required (model_type, architectures, hidden_size) |
Required | Converted into Modelfile | Required |
adapter_config.json |
Standard PEFT schema (r, lora_alpha, target_modules) |
Standard PEFT schema | Converted to GGUF adapter | Mapped to TRT LoRA layers |
| Tensor Key Format | model.layers.0... |
model.layers.0... |
GGUF key paths | TRT layer names |
| Chat Template | Jinja2 (tokenizer_config.json) |
Jinja2 (Radix format) | Ollama TEMPLATE string |
Formatted prompt template |
| Supported Engine Versions | >=0.6.0,<0.8.0 |
>=0.3.0,<0.5.0 |
>=0.3.0 |
>=0.9.0 |
Documentation
Explore topic-specific guides in the docs/ directory:
- Core Principles & Overview
- CLI Command Manual & Reference
- Python SDK Reference & Custom Plugin Guide
- Target Engine Specifications
- CI/CD & MLOps Integration Guide
License
AdapterBridge is released under the Apache 2.0 License.
Metadata
Release files for adapterbridge 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| adapterbridge-0.1.1.tar.gz | 28.3 kB | Without provenance | Details for adapterbridge-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| adapterbridge-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for adapterbridge-0.1.1-py3-none-any.whl |
Total release size: 60.6 kB
Release files / adapterbridge-0.1.1.tar.gz
| Download URL | adapterbridge-0.1.1.tar.gz |
|---|---|
| Size | 28.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d98176bede82784e238f44cc313e5e8f10e3958204d9c8480291cc24163458e8
|
|
BLAKE2b-256 checksum How to use checksums |
8133f6813768aef316aaba3f98869f401a3a3bb7e2e96b26c6a118be45d5c2e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / adapterbridge-0.1.1-py3-none-any.whl
| Download URL | adapterbridge-0.1.1-py3-none-any.whl |
|---|---|
| Size | 32.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
221849ea739ff2df5801475ec420bf7db888f8358d832a1102d2328e6c0941b6
|
|
BLAKE2b-256 checksum How to use checksums |
3d3416e44ee96bf6ef1cc6d9d79026bee560d37bda0fc690df49501f4db9e8fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for adapterbridge 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.