WorkWeave Router Artifact Bundles: Complete File Structure and Layout

WorkWeave Router artifact bundles contain six critical files—centroids.bin, model_registry.json, 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 — 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 — 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 — 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 — 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 — 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, rankings.json, and 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, 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 abstracts the embedding logic and validates the embedder block against metadata.yaml.

Load the Default Bundle

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

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, 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, quality_means.json, model_axes.json, and metadata.yaml.
• V1 legacy bundles omit tunable parameters, containing only centroids.bin, model_registry.json, rankings.json, and metadata.yaml.
• The artifacts/latest pointer determines the default version, overridable via ROUTER_CLUSTER_VERSION.
• The LoadBundle function in 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 and model_axes.json, enabling runtime tuning of α, speed weight, and cost ratio. V1 bundles rely on 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 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. 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. The LoadBundle function reads from the embedded filesystem, validates the embedder against metadata.yaml, and returns a bundle object consumed by internal/router/cluster/scorer.go to create the routing scorer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}