# WorkWeave Router Artifact Bundles: Complete File Structure and Layout

> Understand the WorkWeave Router artifact bundle file structure including centroids bin model registry metadata yaml and version specific JSON files for embedder data

- Repository: [Weave/router](https://github.com/workweave/router)
- Tags: api-reference
- Published: 2026-08-30

---

**WorkWeave Router artifact bundles contain six critical files—`centroids.bin`, [`model_registry.json`](https://github.com/workweave/router/blob/main/model_registry.json), [`metadata.yaml`](https://github.com/workweave/router/blob/main/metadata.yaml), and version-specific JSON files—that store frozen embedder data required for cluster-scoring routing decisions.**

The **WorkWeave Router** uses artifact bundles to package the frozen data required by its cluster-scoring embedder. Stored under `internal/router/cluster/artifacts/`, these bundles follow a strict layout that the runtime loads via `go:embed` to initialize routing intelligence.

## Core Files in WorkWeave Router Artifact Bundles

Each bundle resides in a versioned subdirectory (e.g., `artifacts/v0.75/`) and contains a specific set of binary and JSON files. The exact composition depends on whether the bundle follows the **v1 legacy format** or the modern **v2 format**.

### Binary and Configuration Files

All bundle versions contain three foundational files:

- **`centroids.bin`** — A binary file storing pre-computed embedder centroids used for nearest-neighbor scoring during request routing.
- **[`metadata.yaml`](https://github.com/workweave/router/blob/main/metadata.yaml)** — A YAML descriptor recording provenance (training date, embedder block, version) and embedder specifications (`model`, `embed_dim`, `max_tokens`). The loader validates the embedder against this block before initializing the scorer.
- **[`model_registry.json`](https://github.com/workweave/router/blob/main/model_registry.json)** — A JSON map of model identifiers to metadata (provider, pricing). According to the source code, this is the only hand-editable file in the bundle; the trainer writes it automatically during bundle generation.

### Runtime-Tunable Data (v2 Bundles)

Modern **v2 bundles** include additional files that enable runtime-tunable routing knobs:

- **[`quality_means.json`](https://github.com/workweave/router/blob/main/quality_means.json)** — Contains per-cluster, per-model quality-mean values `Q̄[k][m]`. These values power runtime adjustments for α (alpha), speed weight, and cost ratio parameters.
- **[`model_axes.json`](https://github.com/workweave/router/blob/main/model_axes.json)** — Stores raw per-model axes including input cost, output cost, TTFT (Time To First Token), TPS (Tokens Per Second), and verbosity tokens. The scorer uses this data to reconstruct routing knobs at request time.

### Legacy Scalar Scores (v1 Bundles)

**V1 bundles** (and optionally v2 bundles during dual-write periods) contain:

- **[`rankings.json`](https://github.com/workweave/router/blob/main/rankings.json)** — A scalar score table for each cluster-model pair. The legacy format bakes α, speed weight, and output-cost ratio at training time, making runtime adjustments impossible without regenerating the bundle.

## Bundle Versions and Directory Layout

The Router distinguishes between **v2 bundles** (current) and **v1 legacy bundles** through directory structure and file presence.

V2 bundles live under `internal/router/cluster/artifacts/<version>/` with the full file set described above. **Legacy v1 bundles** reside under `artifacts/legacy/` and contain only `centroids.bin`, [`model_registry.json`](https://github.com/workweave/router/blob/main/model_registry.json), [`rankings.json`](https://github.com/workweave/router/blob/main/rankings.json), and [`metadata.yaml`](https://github.com/workweave/router/blob/main/metadata.yaml).

The `artifacts/latest` pointer file contains the default version name (e.g., `v0.75`). The runtime resolves this automatically unless you override it via the `ROUTER_CLUSTER_VERSION` environment variable. As implemented in [`internal/router/cluster/artifacts.go`](https://github.com/workweave/router/blob/main/internal/router/cluster/artifacts.go), the loader transparently resolves bundles from either the top-level `artifacts/` directory or the `artifacts/legacy/` subdirectory based on the requested version.

## Loading Bundles in Go

The `LoadBundle` function in [`internal/router/cluster/artifacts.go`](https://github.com/workweave/router/blob/main/internal/router/cluster/artifacts.go) abstracts the embedding logic and validates the embedder block against [`metadata.yaml`](https://github.com/workweave/router/blob/main/metadata.yaml).

### Load the Default Bundle

```go
package main

import (
	"context"
	"fmt"
	"log"

	"workweave/router/internal/router/cluster"
)

func main() {
	// Load the default bundle (the version pointed to by artifacts/latest)
	bundle, err := cluster.LoadBundle(context.Background(), "")
	if err != nil {
		log.Fatalf("failed to load cluster bundle: %v", err)
	}
	fmt.Printf("Loaded bundle version %s with %d models\n",
		bundle.Version, len(bundle.ModelRegistry))
}

```

### Inspect Specific Version Files

```go
package main

import (
	"fmt"
	"io/fs"
	"log"

	"workweave/router/internal/router/cluster"
)

func main() {
	b, err := cluster.LoadBundle(context.Background(), "v0.75")
	if err != nil {
		log.Fatalf("load: %v", err)
	}
	// List embedded files for the version
	entries, _ := fs.ReadDir(cluster.EmbeddedArtifacts, "artifacts/v0.75")
	for _, e := range entries {
		fmt.Println(e.Name())
	}
}

```

These examples use the `cluster.EmbeddedArtifacts` filesystem exposed by [`artifacts.go`](https://github.com/workweave/router/blob/main/artifacts.go), which contains all bundles embedded via `go:embed`.

## Summary

- **WorkWeave Router artifact bundles** store frozen embedder data under `internal/router/cluster/artifacts/<version>/`.
- **V2 bundles** contain `centroids.bin`, [`model_registry.json`](https://github.com/workweave/router/blob/main/model_registry.json), [`quality_means.json`](https://github.com/workweave/router/blob/main/quality_means.json), [`model_axes.json`](https://github.com/workweave/router/blob/main/model_axes.json), and [`metadata.yaml`](https://github.com/workweave/router/blob/main/metadata.yaml).
- **V1 legacy bundles** omit tunable parameters, containing only `centroids.bin`, [`model_registry.json`](https://github.com/workweave/router/blob/main/model_registry.json), [`rankings.json`](https://github.com/workweave/router/blob/main/rankings.json), and [`metadata.yaml`](https://github.com/workweave/router/blob/main/metadata.yaml).
- The `artifacts/latest` pointer determines the default version, overridable via `ROUTER_CLUSTER_VERSION`.
- The `LoadBundle` function in [`internal/router/cluster/artifacts.go`](https://github.com/workweave/router/blob/main/internal/router/cluster/artifacts.go) handles embedding, validation, and runtime loading.

## Frequently Asked Questions

### What is the difference between v1 and v2 WorkWeave Router artifact bundles?

V2 bundles contain [`quality_means.json`](https://github.com/workweave/router/blob/main/quality_means.json) and [`model_axes.json`](https://github.com/workweave/router/blob/main/model_axes.json), enabling runtime tuning of α, speed weight, and cost ratio. V1 bundles rely on [`rankings.json`](https://github.com/workweave/router/blob/main/rankings.json), which bakes these parameters at training time and cannot be adjusted without regenerating the bundle. The runtime in [`internal/router/cluster/artifacts.go`](https://github.com/workweave/router/blob/main/internal/router/cluster/artifacts.go) transparently handles both formats.

### How do I specify which bundle version the WorkWeave Router uses?

Set the `ROUTER_CLUSTER_VERSION` environment variable to the desired version string (e.g., `v0.75`). If unset, the runtime reads the version name from `artifacts/latest` and loads the corresponding bundle from `internal/router/cluster/artifacts/`.

### Which file in the bundle should I edit to change model metadata?

Edit [`model_registry.json`](https://github.com/workweave/router/blob/main/model_registry.json). According to the bundle README and source code comments, this is the only hand-editable file in the artifact bundle. All other JSON and binary files are generated automatically by the training pipeline and should not be modified manually.

### How are artifact bundles embedded into the Router binary?

Bundles are embedded using Go's `//go:embed` directive defined in [`internal/router/cluster/artifacts.go`](https://github.com/workweave/router/blob/main/internal/router/cluster/artifacts.go). The `LoadBundle` function reads from the embedded filesystem, validates the embedder against [`metadata.yaml`](https://github.com/workweave/router/blob/main/metadata.yaml), and returns a bundle object consumed by [`internal/router/cluster/scorer.go`](https://github.com/workweave/router/blob/main/internal/router/cluster/scorer.go) to create the routing scorer.