> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Versioning

> How Avra manages the Graph Foundation Model, your Relational Foundation Model, and the downstream models served from both — with versioning, aliases, and rollback you control.

Avra operates a three-layer model architecture. Each layer has its own versioning surface, and each layer's evolution is independent of the others.

## Model layers

### Graph Foundation Model (GFM)

The pre-trained base layer that understands the relational economy — entities, relationships, behaviors, and temporal dynamics. The GFM is operated and improved by Avra. New GFM versions are released periodically and become available to all customers; you choose when to consume them.

### Relational Foundation Model (RFM)

A customer-specific relational representation layer, pre-trained on your schema and temporal business data, then composed with the GFM for downstream models. The RFM is exclusive to your workspace, optionally deployed inside your environment, and evolves as new data lands and as you train downstream models on top of it.

### Downstream Models

Task-specific models — credit, fraud, growth, custom — trained on top of the GFM and your RFM. Each downstream model has its own version history and lifecycle, independent of the foundations beneath it.

## Versioning

### Multiple live versions

Avra supports multiple live versions of each model simultaneously. This allows you to:

* Test new foundation versions without disrupting production
* Run challenger experiments alongside production traffic
* Serve specialized variants for different segments or workflows
* Roll back instantly when something regresses

### Version identification

Each model is identified by **`model_id`**. Each version has a unique, immutable **`version_id`**, and can carry a human-readable **alias** for easier reference.

Common aliases:

* **`production`** — the version currently serving production traffic
* **`challenger`** — a new version being evaluated for promotion
* **`baseline`** — the previous version, kept for comparison

An alias can point to only one version of a given model at a time. The same alias name (e.g. `production`) can be used independently across different models.

## You control upgrades and rollbacks

You decide which versions serve your production traffic — not us.

**Alias management.** Repoint an alias to a different version to upgrade or roll back. API calls referencing the alias pick up the change without any code edit on your side.

```
POST /v1/api/prediction/{model_id}/production
```

**Direct version reference.** Pin to an exact `version_id` when you want guaranteed determinism — useful for backtests, audit replays, or staged rollouts.

```
POST /v1/api/prediction/{model_id}/{version_id}
{
  "legal_document": "12345678000199"
}
```

**Rollback.** Reassign the alias back to the previous stable version. Changes take effect within minutes across all production traffic. No deployment, no incident bridge.

## Promotion process

New downstream model versions are validated before they are made available for promotion:

* **Offline evaluation** against holdout datasets and your historical outcomes
* **Shadow traffic** comparison against the current production version
* **Distributional checks** to surface population-level drift before it reaches customers
* **Statistical consistency** guarantees so score distributions remain interpretable across versions

You receive notification when a new version is available. You choose when — and whether — to upgrade.