# How to Refresh the Model Metadata Catalog in Apache Maka

> Refresh the model metadata catalog in Apache Maka using npm run sync:model-metadata -- --refresh. Fetch, validate, and regenerate catalog files efficiently.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-12

---

**Use `npm run sync:model-metadata -- --refresh` to fetch the latest models.dev API data, validate it against shrinkage rules, and regenerate the TypeScript catalog files atomically.**

The Apache Maka project maintains a synchronized catalog of AI model metadata to ensure accurate provider information and pricing data across its core and runtime packages. This catalog lives in [`packages/core/src/model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-metadata.generated.ts) and is derived from the public **models.dev** API. Refreshing this catalog requires executing a specialized synchronization script that handles data projection, validation, and atomic file replacement.

## Understanding the Model Metadata Architecture

Maka's catalog system relies on a **snapshot-based workflow** that bridges upstream API changes with version-controlled TypeScript source files. The `scripts/sync-model-metadata.mjs` driver orchestrates the entire pipeline, converting raw JSON from models.dev into four internal data structures: `metadata`, `pricing`, `providerFacts`, and `providerOverrides`.

The generated outputs include:

- [`packages/core/src/model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-metadata.generated.ts) – Exports `GENERATED_MODELS_DEV_METADATA` containing per-provider model definitions
- [`packages/runtime/src/telemetry/model-pricing.generated.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/telemetry/model-pricing.generated.ts) – Exports `GENERATED_MODEL_PRICES` for runtime cost calculations
- [`scripts/model-metadata/models-dev-api.snapshot.json`](https://github.com/apache/maka/blob/main/scripts/model-metadata/models-dev-api.snapshot.json) – The committed SHA-256 hashed snapshot used for reproducibility and drift detection

## Executing a Standard Refresh

To update the catalog with the latest live upstream data, run the npm script with the refresh flag. This invokes the `main()` function in `scripts/sync-model-metadata.mjs`, which fetches data from the `SOURCE_URL`, projects it into internal maps, and writes new snapshot and TypeScript files.

```bash
npm run sync:model-metadata -- --refresh

```

This command executes six distinct phases: fetching upstream data via `readUpstream()`, projecting raw JSON through `buildProjection()`, validating against shrinkage with `assertProjectionDoesNotShrink()`, digesting the snapshot with SHA-256, generating TypeScript modules, and performing atomic file replacement via `replaceFilesTransactionally()`.

## Handling Edge Cases and Variations

### Refreshing from a Local File

When testing changes or working offline, bypass the live API by providing a local JSON file that mimics the models.dev response structure using the `--refresh-input` flag.

```bash
npm run sync:model-metadata -- \
  --refresh \
  --refresh-input path/to/local/models-dev.json

```

### Accepting Upstream Removals

By default, the refresh fails if any provider or model present in the previous snapshot disappears from the new data. This **shrinkage protection** prevents accidental data loss. To deliberately remove discontinued providers, pass the `--accept-upstream-removals` flag:

```bash
npm run sync:model-metadata -- \
  --refresh \
  --accept-upstream-removals

```

The validation logic checks `if (!options.acceptUpstreamRemovals)` before calling `assertProjectionDoesNotShrink()` against the previous projection loaded via `loadSnapshotIfPresent()`.

### Verification Without Writing

Use the `--check` flag to validate that existing generated files match the committed snapshot without fetching new data or writing files. This is ideal for CI pipelines ensuring repository consistency.

```bash
npm run sync:model-metadata -- --check

```

Alternatively, use `--drift` to report differences without failing or writing:

```javascript
const report = await main(['node', 'sync-model-metadata.mjs', '--drift']);

```

## Programmatic Integration

Import the `main` function directly from `scripts/sync-model-metadata.mjs` to refresh catalogs within Node.js applications or test suites.

```javascript
import { main } from './scripts/sync-model-metadata.mjs';

// Full refresh with writes
await main(['node', 'sync-model-metadata.mjs', '--refresh']);

// Read-only drift detection
const driftReport = await main(['node', 'sync-model-metadata.mjs', '--drift']);

```

## Critical Implementation Files

Understanding these source files helps debug refresh failures or extend functionality:

- **`scripts/sync-model-metadata.mjs`** – Core driver implementing `main()`, `buildProjection()`, and `replaceFilesTransactionally()`
- **[`packages/core/src/model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-metadata.generated.ts)** – Generated TypeScript containing `GENERATED_MODELS_DEV_METADATA`
- **[`packages/runtime/src/telemetry/model-pricing.generated.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/telemetry/model-pricing.generated.ts)** – Generated pricing constants used by telemetry systems
- **[`scripts/model-metadata/models-dev-api.snapshot.json`](https://github.com/apache/maka/blob/main/scripts/model-metadata/models-dev-api.snapshot.json)** – Version-controlled JSON snapshot with SHA-256 digest

## Summary

- **Refresh the model metadata catalog** by running `npm run sync:model-metadata -- --refresh` to fetch models.dev data and regenerate TypeScript sources
- **Prevent data loss** through default shrinkage protection that rejects removals unless `--accept-upstream-removals` is specified
- **Test locally** using `--refresh-input` with a local JSON file to avoid hitting the live API
- **Validate consistency** via `--check` for CI workflows or `--drift` for reporting
- **Atomic writes** ensure [`packages/core/src/model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-metadata.generated.ts) and related files are never partially updated

## Frequently Asked Questions

### Why does my refresh fail with a shrinkage error?

The refresh aborts when providers or models from the previous snapshot are missing in the new upstream data. This prevents accidental deletion of metadata. Run with `--accept-upstream-removals` only if you intentionally want to remove discontinued models from the catalog.

### Can I refresh the catalog without internet access?

Yes. Save a local copy of the models.dev API response as JSON, then run `npm run sync:model-metadata -- --refresh --refresh-input ./local-file.json`. The script reads from this path instead of fetching `SOURCE_URL`, making it suitable for air-gapped environments or reproducible CI builds.

### How do I verify the generated files match the repository state?

Execute `npm run sync:model-metadata -- --check`. This compares the current snapshot against the generated TypeScript files without fetching new data or writing to disk, returning a non-zero exit code if they differ. This ensures the committed generated files are synchronized with the snapshot.

### What happens if the refresh is interrupted mid-process?

The `replaceFilesTransactionally()` function stages temporary copies and only swaps them after all writes succeed. If the process crashes during generation, the original [`model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/model-metadata.generated.ts) and snapshot files remain intact, preventing corruption or half-written states.