# How to Refresh Maka's Model Metadata Catalog: A Complete Guide

> Refresh Maka's AI model metadata catalog with a simple command. Learn how to sync the latest data, validate it, and regenerate TypeScript files for the apache mako repository.

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

---

**Refresh Maka's AI model metadata catalog by running `npm run sync:model-metadata -- --refresh`, which fetches the latest upstream data from models.dev, validates it, and regenerates the TypeScript source files.**

Maka maintains a generated catalog of AI provider metadata and pricing data in its source tree. This catalog — stored in [`packages/core/src/model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-metadata.generated.ts) — must be periodically synchronized with the upstream **models.dev** API. The `scripts/sync-model-metadata.mjs` script automates this entire workflow, from fetching raw data to atomically replacing generated files.

## Understanding the Model Metadata Refresh Architecture

The refresh pipeline in `apache/maka` is designed for safety, reproducibility, and auditability. All transformations are deterministic and version-controlled through a committed snapshot file.

### Source and Generated Files

| File | Purpose |
|------|---------|
| `scripts/sync-model-metadata.mjs` | Core orchestration script |
| [`scripts/model-metadata/models-dev-api.snapshot.json`](https://github.com/apache/maka/blob/main/scripts/model-metadata/models-dev-api.snapshot.json) | Committed snapshot of upstream API response |
| [`packages/core/src/model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-metadata.generated.ts) | Generated model metadata exports |
| [`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 tables (optional) |

## Running a Standard Catalog Refresh

The standard workflow fetches live data from models.dev and regenerates all TypeScript sources.

### Command Syntax

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

```

This executes the `main()` entry point in `scripts/sync-model-metadata.mjs` with the following stages:

1. **Fetch upstream data** via `readUpstream(SOURCE_URL)`
2. **Project** raw JSON into internal maps (`buildProjection()`)
3. **Validate** against shrinkage rules
4. **Write snapshot** with SHA-256 digest
5. **Generate TypeScript modules** with provenance headers
6. **Atomic file replacement** via `replaceFilesTransactionally()`

## Refresh Options and Flags

### Refresh from Local File (Offline/CI Reproducibility)

Use `--refresh-input` to bypass live API calls and use a saved response:

```bash
npm run sync:model-metadata -- \
  --refresh \
  --refresh-input scripts/model-metadata/models-dev-api.snapshot.json

```

This pattern ensures CI builds remain deterministic even if models.dev is unavailable.

### Accept Upstream Removals

By default, the refresh refuses to drop providers or models that existed in the previous snapshot. This guard prevents accidental data loss.

Override with `--accept-upstream-removals` when providers are legitimately discontinued:

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

```

The validation logic in `sync-model-metadata.mjs` implements this check:

```ts
if (!options.acceptUpstreamRemovals) {
  const previous = await loadSnapshotIfPresent(snapshotPath);
  if (previous) assertProjectionDoesNotShrink(previous.projection, projection);
}

```

### Verify Without Writing (`--check`)

Validate that generated files match the committed snapshot without modifying any files:

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

```

Useful for pre-commit hooks or CI gates.

## Programmatic Refresh Control

Import and invoke the refresh pipeline directly from Node.js:

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

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

// Drift detection only (no writes)
const report = await main(['node', 'sync-model-metadata.mjs', '--drift']);
console.log(report);

```

## The Projection Pipeline: How Raw Data Becomes TypeScript

The `buildProjection()` function in `scripts/sync-model-metadata.mjs` transforms the raw models.dev response into four structured maps:

- **`metadata`** — per-provider model capabilities via `toMetadata`
- **`pricing`** — token cost data via `toPricing`
- **`providerFacts`** — static provider attributes
- **`providerOverrides`** — SDK-specific runtime adjustments

These projections are then serialized with full provenance:

```ts
// Excerpt from generated file header
// Source: scripts/model-metadata/models-dev-api.snapshot.json
// SHA-256: abc123...
// Retrieved: 2024-01-15T09:23:17Z

```

## Atomic File Replacement Guarantees

The `replaceFilesTransactionally()` function ensures the catalog is never in a partially-written state:

1. Write all new content to temporary paths
2. Create backups of existing files
3. Rename temporaries to final paths only after all writes succeed
4. Clean up backups on success, or restore on failure

This mechanism protects against corruption during interrupted refreshes.

## Summary

- **Primary command**: `npm run sync:model-metadata -- --refresh` refreshes Maka's model metadata catalog from the live models.dev API
- **Local testing**: Use `--refresh-input path/to/local.json` for offline or reproducible refreshes
- **Safety guard**: `--accept-upstream-removals` is required to drop previously-known providers or models
- **Verification**: `--check` validates generated files without writing
- **Core files**: `scripts/sync-model-metadata.mjs` drives the process; outputs land in [`packages/core/src/model-metadata.generated.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-metadata.generated.ts)
- **Atomic writes**: The refresh uses transactional file replacement to prevent corruption

## Frequently Asked Questions

### What happens if the upstream API removes a provider I still need?

The refresh fails with an assertion error unless you pass `--accept-upstream-removals`. This prevents silent data loss when providers disappear from models.dev. If you need to retain a discontinued provider, you must fork the snapshot or maintain local overrides.

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

Yes. Save a copy of the models.dev response as JSON, then run:

```bash
npm run sync:model-metadata -- --refresh --refresh-input ./saved-response.json

```

This pattern is used in `apache/maka` CI to ensure reproducible builds.

### How do I know which snapshot version generated my TypeScript files?

Each generated file includes a header comment with the snapshot's SHA-256 hash and retrieval timestamp. Compare this against [`scripts/model-metadata/models-dev-api.snapshot.json`](https://github.com/apache/maka/blob/main/scripts/model-metadata/models-dev-api.snapshot.json) to verify provenance.

### What is the difference between `--check` and `--drift`?

Both perform read-only validation. `--check` exits with error code if generated files differ from the snapshot, suitable for CI gates. `--drift` returns a detailed report object for programmatic consumption without modifying exit behavior.