AIR Format Specification

The Architecture-Agnostic Intermediate Representation (AIR) format is the cornerstone of UAL Adapter’s portability.

Format Structure

An AIR file is a JSON file with the following structure:

{
  "metadata": {
    "version": "0.1.0",
    "source_architecture": "gpt2",
    "domain": "medical",
    "rank": 16,
    "alpha": 32,
    "created_at": "2025-01-15T10:30:00",
    "training_config": {...}
  },
  "adapters": [
    {
      "semantic_role": "attention_query",
      "layer_index": 0,
      "lora_A": [[...], ...],
      "lora_B": [[...], ...],
      "original_shape": [768, 768],
      "rank": 16
    },
    ...
  ]
}

Semantic Roles

UAL defines universal semantic roles for model parameters:

Attention Roles

attention_query - Query projection (Q in attention)
attention_key - Key projection (K in attention)
attention_value - Value projection (V in attention)
attention_output - Output projection after attention

MLP Roles

mlp_up - Up-projection in feed-forward network
mlp_down - Down-projection in feed-forward network
mlp_gate - Gate projection (for gated architectures like LLaMA)

Layer Indexing

Layers are indexed starting from 0. The format preserves layer information to enable:

Layer-specific transfer strategies
Selective layer adaptation
Cross-layer analysis

LoRA Weight Storage

Each adapter stores two matrices:

lora_A: Low-rank matrix A (rank × in_features)
lora_B: Low-rank matrix B (out_features × rank)

The effective weight update is: ΔW = (alpha/rank) * B @ A

Metadata Fields

version

AIR format version for compatibility checking.

source_architecture

Original model architecture (e.g., “gpt2”, “llama”).

domain

Domain identifier for the adapter.

rank

LoRA rank used during training.

alpha

LoRA scaling factor.

created_at

ISO 8601 timestamp of creation.

training_config

Additional training configuration (optional).

Compatibility

AIR format is designed for forward compatibility:

New fields can be added without breaking old readers
Version checking enables format evolution
Architecture-agnostic design supports new models

Import Process

When importing an AIR adapter:

Parse JSON structure
Validate format version
Map semantic roles to target architecture
Check dimension compatibility
Project dimensions if needed
Apply LoRA weights to model

Export Process

When exporting to AIR:

Extract LoRA weights from model
Detect source architecture
Map parameters to semantic roles
Extract layer indices
Collect metadata
Serialize to JSON

Best Practices

Include comprehensive metadata for reproducibility
Document training configuration
Version your AIR files
Test import/export roundtrip
Validate dimension compatibility before deployment