Implementation:Helicone Helicone BuildIndexes

Knowledge Sources	Helicone
Domains	Model Registry, Indexing, TypeScript
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete function that builds O(1) lookup maps from model/endpoint configurations for fast runtime access, provided by the packages/cost/models/build-indexes.ts module.

Description

The buildIndexes function takes two record objects -- the active model-provider configurations and optionally the archived configurations -- and returns a ModelIndexes object containing 13 pre-computed Map instances. Each Map serves a different query pattern: lookup by composite config ID, by endpoint ID, by model name, by provider name, by provider model ID, or by alias. The function performs a single pass over all configurations, building every index simultaneously, then sorts all endpoint lists by ascending cost.

The function also builds a helper mergeConfigs (internal to the module) that combines a ModelProviderConfig with a per-deployment EndpointConfig, applying fallback logic where deployment-level values override model-level values.

The returned ModelIndexes object is the primary data structure consumed by the gateway's routing layer, cost calculator, and model selection UI.

Usage

Use this function at application startup to build the lookup indexes from the flat model-provider configuration records. The returned ModelIndexes should be stored as a long-lived, shared reference for the duration of the process.

Code Reference

Source Location

• Repository: Helicone
• File: packages/cost/models/build-indexes.ts (lines 70-223)

Signature

export function buildIndexes(
  modelProviderConfigs: Record<string, ModelProviderConfig>,
  archivedModelProviderConfigs: Record<string, ModelProviderConfig> = {}
): ModelIndexes;

export interface ModelIndexes {
  endpointConfigIdToEndpointConfig: Map<ModelProviderConfigId, ModelProviderConfig>;
  endpointIdToEndpoint: Map<EndpointId, Endpoint>;
  modelToPtbEndpoints: Map<ModelName, Endpoint[]>;
  modelProviderIdToPtbEndpoints: Map<ModelProviderConfigId, Endpoint[]>;
  providerToModels: Map<ModelProviderName, Set<ModelName>>;
  modelToEndpointConfigs: Map<ModelName, ModelProviderConfig[]>;
  modelToProviders: Map<ModelName, Set<ModelProviderName>>;
  modelToEndpoints: Map<ModelName, Endpoint[]>;
  modelToProviderData: Map<ModelName, ModelProviderEntry[]>;
  modelProviderToData: Map<ModelProviderConfigId, ModelProviderEntry>;
  providerModelIdToConfig: Map<string, ModelProviderConfig>;
  providerModelIdAliasToConfig: Map<string, ModelProviderConfig>;
  modelToArchivedEndpointConfigs: Map<string, ModelProviderConfig>;
}

export interface ModelProviderEntry {
  provider: ModelProviderName;
  config: ModelProviderConfig;
  ptbEndpoints: Endpoint[];
}

Import

import { buildIndexes, ModelIndexes, ModelProviderEntry } from "packages/cost/models/build-indexes";

I/O Contract

Inputs

Name	Type	Required	Description
modelProviderConfigs	Record<string, ModelProviderConfig>	Yes	Flat object of all active model-provider configurations, keyed by "modelName:providerName" composite strings
archivedModelProviderConfigs	Record<string, ModelProviderConfig>	No (defaults to {})	Flat object of archived/versioned configurations for historical lookups

Outputs

Name	Type	Description
endpointConfigIdToEndpointConfig	Map<ModelProviderConfigId, ModelProviderConfig>	O(1) lookup of base configuration by "model:provider" composite key
endpointIdToEndpoint	Map<EndpointId, Endpoint>	O(1) lookup of resolved endpoint by "model:provider:deployment" triple key
modelToPtbEndpoints	Map<ModelName, Endpoint[]>	Cost-sorted PTB-enabled endpoints for each model
modelProviderIdToPtbEndpoints	Map<ModelProviderConfigId, Endpoint[]>	Cost-sorted PTB-enabled endpoints grouped by model:provider
providerToModels	Map<ModelProviderName, Set<ModelName>>	Set of models offered by each provider
modelToEndpointConfigs	Map<ModelName, ModelProviderConfig[]>	All provider configurations for each model
modelToProviders	Map<ModelName, Set<ModelProviderName>>	Set of providers that serve each model
modelToEndpoints	Map<ModelName, Endpoint[]>	Cost-sorted list of all endpoints (PTB and non-PTB) for each model
modelToProviderData	Map<ModelName, ModelProviderEntry[]>	Structured provider data entries for each model, including config and PTB endpoints
modelProviderToData	Map<ModelProviderConfigId, ModelProviderEntry>	Direct lookup of provider data by model:provider key
providerModelIdToConfig	Map<string, ModelProviderConfig>	Lookup by "providerModelId:provider" key
providerModelIdAliasToConfig	Map<string, ModelProviderConfig>	Lookup by alias "aliasId:provider" key
modelToArchivedEndpointConfigs	Map<string, ModelProviderConfig>	Archived/versioned configurations indexed by version key

Usage Examples

Basic Usage

import { buildIndexes } from "packages/cost/models/build-indexes";

// Flatten all endpoint exports into a single record
const allConfigs: Record<string, ModelProviderConfig> = {
  ...anthropicEndpointConfig,
  ...openaiEndpointConfig,
  ...googleEndpointConfig,
  // ... more authors
};

const archivedConfigs: Record<string, ModelProviderConfig> = {
  // versioned/archived entries
};

// Build all indexes at startup
const indexes = buildIndexes(allConfigs, archivedConfigs);

// Query: which providers serve "claude-opus-4"?
const providers = indexes.modelToProviders.get("claude-opus-4");
// => Set { "anthropic", "vertex", "bedrock", "openrouter", "helicone" }

// Query: cheapest PTB endpoint for "claude-opus-4"
const cheapest = indexes.modelToPtbEndpoints.get("claude-opus-4")?.[0];
// => Endpoint with lowest input + output cost

// Query: resolve a specific endpoint
const endpoint = indexes.endpointIdToEndpoint.get(
  "claude-opus-4:bedrock:us-east-1"
);

// Query: all models available from "openai" provider
const openaiModels = indexes.providerToModels.get("openai");

Related Pages

Implements Principle

• Principle:Helicone_Helicone_Central_Registry_Indexing