portallib 0.1.2

Generate portable task-specific LoRA adapters across language models

PorTAL: Portable Task Adapters for LLMs

Alpha research release announced by Ramp Labs. APIs and artifact schemas may evolve before the first stable release.

PorTAL learns a base-agnostic task latent and a light per-base decoder that generates ordinary per-layer LoRA weights. A task can be trained once, adapted to supported frozen base models, and exported as a standard Hugging Face PEFT adapter.

portallib is an alpha Python library for loading, training, saving, publishing, and exporting PorTAL artifacts with standard PyTorch and Hugging Face interfaces.

The included pinned recipes reproduce the PorTAL source-training, target-refitting, and evaluation method described by Ramp Labs. Reported results should be generated from the released artifacts and their recorded evaluation configuration rather than treated as fixed package guarantees.

During source training, PorTAL jointly learns the task-latent table, one shared canonical core, and one alignment for each source base. To port the learned tasks, it freezes the latent table and core and refits only a fresh alignment for the target base. The resulting task adapter is exportable as an ordinary PEFT LoRA adapter.

Install

Install the inference library from PyPI:

pip install portallib

Install the optional Hugging Face model and dataset dependencies for training:

pip install 'portallib[training]'

Python 3.11 and 3.12 are supported. Install a CUDA-compatible PyTorch build for GPU training before installing the training extra when your platform requires a specific CUDA wheel.

Load and export

Load a native PorTAL artifact, select a trained task, and obtain a normal PEFT model:

from transformers import AutoModelForCausalLM
from portallib import PortalModel

base = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-4B",
    revision="1cfa9a7208912126459214e8b04321603b3df60c",
)
portal = PortalModel.from_pretrained(
    "RampPublic/portal-qwen3-4b",
    revision="v0.1.0",
    base_model=base,
)
model = portal.get_peft_model("rte")
model.save_pretrained("./portal-rte-qwen3-4b")

A task can also be exported without loading the base LLM:

portal.export_peft("rte", "./portal-rte-qwen3-4b")

The exported directory is an ordinary PEFT adapter and reloads with PeftModel.from_pretrained.

Published artifacts

Artifact	Role
RampPublic/portal-qwen3-1.7b	Jointly trained shared weights plus the 1.7B alignment
RampPublic/portal-qwen3-4b	Jointly trained shared weights plus the 4B alignment
RampPublic/portal-qwen3-8b	1,000-example-per-task refit
RampPublic/portal-gemma-3-4b	1,000-example-per-task cross-family refit

The recipes load the v0.1.0 artifact revisions. Each repository contains one base-specific native PorTAL artifact; task-specific standard PEFT adapters can be generated from it as needed.

Examples

examples/train_example.py is thin orchestration around the public canonical trainer APIs. It freezes each base model, jointly learns shared task latents and a canonical core with one thin alignment per source base, evaluates epoch zero and every training epoch, restores the best held-out epoch, and writes one native artifact per source base. Its only model downloads are the raw Hugging Face bases selected for source training.

The complete pinned recipe is a short, editable block near the top of the file. It selects the dataset, exact model revisions, output directory, source bases, and PortalTrainingConfig:

python examples/train_example.py

examples/refit_example.py loads either source artifact as a carrier for the task vectors and canonical core learned jointly from Qwen3-1.7B and Qwen3-4B. It downloads only the new raw target base, freezes the shared components, and trains a fresh target alignment:

python examples/refit_example.py

The checked-in recipe reads the shared weights from RampPublic/portal-qwen3-4b; this does not make the refit 4B-only—the 1.7B and 4B source artifacts contain identical jointly trained task latents and canonical core weights. The default target is Qwen3-8B with at most 1,000 training examples per task. The adjacent Gemma 3 recipe uses the same shared components and its exact text-decoder layer path.

examples/evaluate_example.py loads a trained PorTAL artifact and its matching raw base, then reports the base floor, adapted per-task metrics, macro metrics, and accuracy lift:

python examples/evaluate_example.py

The checked-in evaluation recipe uses RampPublic/portal-qwen3-8b; change the artifact and matching base recipe together to evaluate one of the other published source or refit artifacts.

The examples are repository assets rather than installed console commands. Clone the repository to run them, then install the released training package:

git clone https://github.com/ramp-public/portallib
cd portallib
pip install 'portallib[training]==0.1.2'
python examples/train_example.py

REPRODUCING.md records pinned dataset and model revisions, the complete training configuration, checkpoint selection, and source/Qwen/Gemma recipes.

COMPUTE.md shows how to run any example locally with Docker or remotely through Modal. The compute wrapper provisions the runtime and persistent storage; the training and evaluation behavior comes from the installed portallib release and selected recipe.

Model compatibility

PorTAL supports Qwen3 and cross-family refitting to Gemma 3. Qwen3 exposes decoder layers at model.layers; Gemma 3 exposes its text decoder at model.language_model.layers. The default projection paths cover the usual query, key, value, attention-output, and gated-MLP linear modules used by those families.

Other causal language-model families are expected to work when they expose uniform linear projections across decoder layers. Pass their exact layer and projection paths through PortalBase; PorTAL validates every configured path and dimension before training. Automatic architecture adapters and models with non-uniform per-layer projection dimensions are not yet part of the supported v0.1 compatibility surface. Contributions that add exact, tested architecture mappings are welcome.

For another model family, set its exact BaseRecipe.layer_path; paths are explicit rather than inferred from module-name patterns, so an incompatible model fails before training.

The checked-in modules=("q", "v") setting generates LoRA for query/value projections. Set it to ("q", "k", "v", "o", "gate", "up", "down") to include the attention output and MLP projections. In both cases, the base model parameters remain frozen.

Artifact format

Native artifacts use the standard Hugging Face layout:

• config.json contains the schema version, base model and revision, task names, LoRA settings, exact layer/module paths, and projection dimensions.
• model.safetensors contains task_latents, the canonical core, and one base-specific alignment, with portallib format metadata.
• README.md is the generated model card.

PortalModel inherits ModelHubMixin, so save_pretrained, from_pretrained, and push_to_hub follow standard Hugging Face Hub behavior:

portal.push_to_hub("your-namespace/portal-qwen3-4b", private=True)

Configured layers and projections are resolved deterministically. Missing modules, incompatible dimensions, unknown schema versions, and inconsistent target declarations fail explicitly.

Public API

• PortalConfig validates artifacts and builds exact configurations from supported base models.
• PortalCoreTrainer jointly trains shared latents/core and one alignment per source base using balanced per-task updates, EMA loss normalization, and per-base latent-gradient balancing.
• PortalAdapterRefitter freezes a source artifact's latents/core and trains only a target alignment.
• PortalTrainingConfig.from_portal_config preserves an artifact's architecture while selecting a new optimization recipe for refitting.
• PortalEvaluator batches candidate continuations while reporting character-normalized multiple-choice accuracy and token-mean gold NLL.
• EvaluationResult.to_dict returns the canonical JSON-ready evaluation representation.
• PortalDecoder combines a canonical core and one base-specific alignment to generate LoRA factors.
• PortalModel loads, saves, publishes, materializes, and exports trained artifacts.
• ChoiceDataset loads and saves the normalized local/Hub task schema and supports explicit Hub upload.
• collate_gold_batch provides the causal-LM batch format used by the training APIs.

Development

uv run ruff check src tests examples scripts
uv run pytest -q
uv run python -m build

PorTAL is licensed under Apache-2.0.

Citation

If you use PorTAL, cite the software metadata in CITATION.cff.