Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 | 1x 1x 1x 1x 1x 20x 20x 20x 20x 20x 20x 20x 162x 162x 91x 91x 91x 162x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 20x 25x 25x 25x 25x 25x 25x 25x 36x 36x 22x 36x 19x 19x 36x 36x 15x 15x 15x 11x 15x 11x 11x 11x 11x 15x 15x 36x 4x 4x 21x 21x 21x 21x 1x 1x 1x 1x 1x 1x 21x 21x 15x 15x 14x 14x 14x 14x 14x 14x 14x 12x 12x 12x 2x 2x 36x 36x 36x 36x | /**
* ModelDescriptor — the universal contract between ONNX models
* and the TypeScript inference engine.
*
* Generated by `scripts/export-onnx.py` alongside the .onnx file.
* The engine reads this at runtime to configure itself for any
* compatible TimesFM model version, eliminating all hardcoded
* architecture constants.
*
* @module model-descriptor
*/
import * as path from 'node:path';
import { TIMESFM_25_CONFIG, type ModelConfig } from './types';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
/** Schema version the current engine supports. */
export const ENGINE_SUPPORTED_SCHEMA = 1;
/** Model weight precision. */
export type ModelPrecision = 'fp32' | 'int8';
/** Default precision when a descriptor omits the field (backward compat). */
export const PRECISION_DEFAULT: ModelPrecision = 'fp32';
/** ONNX graph shape information extracted from the exported model. */
export interface OnnxDescriptor {
readonly input_name: string;
readonly input_shape: readonly number[];
readonly outputs: Record<string, readonly number[]>;
readonly opset: number;
readonly sha256: string;
readonly size_bytes: number;
/**
* Weight precision of the exported ONNX graph.
* Optional for backward compatibility with schema-1 descriptors
* produced before INT8 support. Defaults to 'fp32' when absent.
*/
readonly precision?: ModelPrecision;
}
/** TimesFM architecture parameters extracted from the PyTorch model. */
export interface ArchitectureDescriptor {
readonly input_patch_len: number;
readonly output_patch_len: number;
readonly output_quantile_len: number;
readonly num_layers: number;
readonly num_heads: number;
readonly model_dims: number;
readonly quantiles: readonly number[];
readonly context_limit: number;
}
/** Pre/post-processing strategy flags. */
export interface ProcessingDescriptor {
readonly preprocessing: string;
readonly postprocessing: readonly string[];
}
/** Model identity metadata. */
export interface ModelIdentity {
readonly version: string;
readonly variant: string;
readonly hf_revision: string;
readonly exported_at: string;
}
/**
* Complete model descriptor — the JSON contract between
* export-onnx.py and the TypeScript engine.
*/
export interface ModelDescriptor {
readonly schema: number;
readonly model: ModelIdentity;
readonly onnx: OnnxDescriptor;
readonly architecture: ArchitectureDescriptor;
readonly processing: ProcessingDescriptor;
}
// ---------------------------------------------------------------------------
// Descriptor → ModelConfig conversion
// ---------------------------------------------------------------------------
/**
* Convert a parsed ModelDescriptor into a ModelConfig for the engine.
* This is the bridge between the self-describing model file and the
* TypeScript inference pipeline.
*/
export function descriptorToModelConfig(desc: ModelDescriptor): ModelConfig {
const arc = desc.architecture;
const onx = desc.onnx;
const quantiles = [...arc.quantiles] as readonly number[];
const numQuantiles = quantiles.length + 1; // +1 for mean at index 0
// Compute the decode index dynamically: find the quantile closest to 0.5 (median).
// The mean is at index 0, and quantile indices start at 1. For the canonical
// [0.1, 0.2, ..., 0.9] quantile set, this resolves to index 5 (q50).
// Dynamically computing it supports models with non-standard quantile levels.
let decodeIndex = 5; // canonical default
let bestDist = Infinity;
for (let q = 0; q < quantiles.length; q++) {
const dist = Math.abs(quantiles[q] - 0.5);
if (dist < bestDist) {
bestDist = dist;
decodeIndex = q + 1; // +1 because index 0 is the mean
}
}
return Object.freeze({
contextLimit: arc.context_limit,
exportedPatches: onx.input_shape[1],
inputPatchLen: arc.input_patch_len,
outputPatchLen: arc.output_patch_len,
outputQuantileLen: arc.output_quantile_len,
outputPatchesPerInput: arc.output_patch_len / arc.input_patch_len,
quantiles,
decodeIndex, // dynamically computed — median quantile position
numLayers: arc.num_layers,
numHeads: arc.num_heads,
modelDims: arc.model_dims,
headDim: arc.model_dims / arc.num_heads,
numQuantiles,
tokenizerInputDims: arc.input_patch_len + arc.input_patch_len,
tokenizerHiddenDims: arc.model_dims,
tokenizerOutputDims: arc.model_dims,
outputPointDims: arc.model_dims,
outputQuantileDims: arc.output_quantile_len * numQuantiles,
});
}
// ---------------------------------------------------------------------------
// Loading
// ---------------------------------------------------------------------------
/**
* Load and parse a model-descriptor.json file.
*
* @param path - Path to the directory containing model-descriptor.json
* (e.g., the same directory as the ONNX file).
* @returns The parsed descriptor, or null if the file doesn't exist
* or is incompatible.
*/
export async function loadModelDescriptor(path: string): Promise<ModelDescriptor | null> {
// Try multiple candidate filenames
const candidates = [
`${path}/model-descriptor.json`,
path.replace(/\.onnx$/, '-descriptor.json'),
path.replace(/\.onnx$/, '.onnx.meta.json'),
];
for (const candidate of candidates) {
try {
const content = await readJsonFile(candidate);
const desc = JSON.parse(content) as ModelDescriptor;
// Normalise missing precision to default for downstream consumers.
if (desc.onnx && !desc.onnx.precision) {
(desc as { onnx: { precision?: string } }).onnx.precision = PRECISION_DEFAULT;
}
return validateDescriptor(desc) ? desc : null;
} catch (err) {
// Distinguish "file not found" from "parse error" — the latter may
// indicate a corrupt descriptor that warrants a warning.
if (
err instanceof Error &&
err.message.includes('ENOENT') === false &&
err.message.includes('no such file') === false
) {
console.warn(
`[timesfm-core] Failed to parse model descriptor at ${candidate}: ${(err as Error).message}`,
);
}
continue;
}
}
return null;
}
/**
* Validate that a descriptor is compatible with the current engine.
*/
function validateDescriptor(desc: ModelDescriptor): boolean {
if (!desc || typeof desc !== 'object') return false;
if (typeof desc.schema !== 'number') return false;
if (desc.schema > ENGINE_SUPPORTED_SCHEMA) {
console.warn(
`Model descriptor schema ${desc.schema} is newer than engine supports ` +
`(${ENGINE_SUPPORTED_SCHEMA}). Please upgrade @agentix-e/timesfm-core.`,
);
return false;
}
if (!desc.architecture || !desc.onnx) return false;
if (!desc.onnx.input_shape || desc.onnx.input_shape.length < 3) return false;
return true;
}
// ---------------------------------------------------------------------------
// Resolution: load descriptor + build ModelConfig
// ---------------------------------------------------------------------------
/**
* Resolve the ModelConfig from a model-descriptor.json file co-located
* with the ONNX model, falling back to a canonical default if no
* descriptor is found.
*
* This is the single entry-point called by {@link TimesFMModel.fromPretrained}.
* It ensures the descriptor is the **single source of truth** for all
* architecture constants — no more hardcoded `TIMESFM_25_CONFIG` in
* business logic.
*
* @param modelPath - Path to an ONNX model file.
* @param fallback - Config to use when no descriptor is found (default: TIMESFM_25_CONFIG).
* @returns The resolved ModelConfig and the parsed descriptor (if any).
*/
export async function resolveModelConfig(
modelPath: string,
fallback: ModelConfig = TIMESFM_25_CONFIG,
): Promise<{ config: ModelConfig; descriptor: ModelDescriptor | null }> {
const dir = path.dirname(modelPath);
const descriptor = await loadModelDescriptor(dir);
if (descriptor) {
const config = descriptorToModelConfig(descriptor);
return { config, descriptor };
}
return { config: fallback, descriptor: null };
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/**
* Platform-agnostic file read. In Node.js, uses fs/promises.
*/
async function readJsonFile(filePath: string): Promise<string> {
// Dynamic import to avoid bundling issues
const { readFile } = await import('node:fs/promises');
return readFile(filePath, 'utf-8');
}
|