Release experimental Transition Foundation Model v0.1 with reproducible source and validation
1baf215 verified Download tfm/api/server.py from maxffarrell/transition-foundation-model: direct link, hf CLI and curl.
- Browser
- Download file 18.2 kB
-
https://huggingface.co/maxffarrell/transition-foundation-model/resolve/main/tfm/api/server.py
- Command line
-
hf download hf://maxffarrell/transition-foundation-model/tfm/api/server.py
-
curl -L -o server.py https://huggingface.co/maxffarrell/transition-foundation-model/resolve/main/tfm/api/server.py
18.2 kB
| """Typed, strict v0.1 prediction API. Start with TFM_CHECKPOINT pointing to a trained artifact.""" | |
| from __future__ import annotations | |
| import hashlib | |
| import json | |
| import os | |
| from pathlib import Path | |
| from typing import Annotated, Literal | |
| import numpy as np | |
| import torch | |
| from fastapi import FastAPI, HTTPException | |
| from pydantic import BaseModel, ConfigDict, Field, StrictFloat, StrictInt | |
| Number = Annotated[StrictFloat | StrictInt, Field(allow_inf_nan=False)] | |
| class StrictModel(BaseModel): | |
| model_config = ConfigDict(extra="forbid") | |
| class FieldMetadata(StrictModel): | |
| name: str | |
| unit: str | |
| role: Literal["state", "action", "exogenous"] | |
| type: Literal["continuous"] = "continuous" | |
| minimum: Number | None = None | |
| maximum: Number | None = None | |
| class SystemSchema(StrictModel): | |
| family: Literal["thermal", "tank", "battery"] | |
| fields: list[FieldMetadata] = Field(min_length=1, max_length=64) | |
| class Observation(StrictModel): | |
| timestamp_minutes: Number | |
| state: dict[str, Number | None] | |
| actions: dict[str, Number] = Field(default_factory=dict) | |
| exogenous: dict[str, Number] = Field(default_factory=dict) | |
| class PredictRequest(StrictModel): | |
| system_schema: SystemSchema = Field(alias="schema") | |
| history: list[Observation] = Field(max_length=96) | |
| state: dict[str, Number | None] | |
| actions: dict[str, dict[str, list[Number]]] = Field(min_length=1, max_length=128) | |
| exogenous: dict[str, list[Number]] | |
| horizons_minutes: list[StrictInt] = Field(min_length=1, max_length=8) | |
| predict: list[str] = Field(min_length=1, max_length=16) | |
| class FieldPrediction(StrictModel): | |
| mean: float | |
| predictive_std: float | |
| interval_90: tuple[float, float] | None | |
| interval_status: Literal["calibrated", "unavailable"] | |
| physically_clipped: bool | |
| class PredictResponse(StrictModel): | |
| model_version: str | |
| predictions: dict[str, dict[str, dict[str, FieldPrediction]]] | |
| indicators: dict[str, bool | str | None] | |
| class PredictionEngine: | |
| def __init__( | |
| self, checkpoints: list[str | Path], calibration: str | Path | None = None, device: str = "cpu" | |
| ): | |
| from tfm.data import FIELD_INDEX, FIELD_SPECS, Normalization | |
| from tfm.training.train import load_checkpoint | |
| if not checkpoints: | |
| raise ValueError("At least one checkpoint is required") | |
| self.device = torch.device(device) | |
| self.models, self.checkpoints = [], [] | |
| self.hashes = [] | |
| for path in checkpoints: | |
| model, checkpoint = load_checkpoint(path, device=device) | |
| model.eval() | |
| self.models.append(model) | |
| self.checkpoints.append(checkpoint) | |
| self.hashes.append(hashlib.sha256(Path(path).read_bytes()).hexdigest()) | |
| normalization_file = Path(path).parent / "normalization.json" | |
| if ( | |
| checkpoint.get("normalization_sha256") | |
| != hashlib.sha256(normalization_file.read_bytes()).hexdigest() | |
| ): | |
| raise ValueError("Checkpoint normalization fingerprint mismatch") | |
| if len(set(self.hashes)) != len(self.hashes): | |
| raise ValueError("Duplicate ensemble checkpoint weights") | |
| self.version = "tfm-0.1.0+" + hashlib.sha256("|".join(sorted(self.hashes)).encode()).hexdigest()[:12] | |
| self.normalization = Normalization.load(Path(checkpoints[0]).parent / "normalization.json") | |
| for path in checkpoints[1:]: | |
| other = Normalization.load(Path(path).parent / "normalization.json") | |
| if not ( | |
| np.array_equal(other.mean, self.normalization.mean) | |
| and np.array_equal(other.scale, self.normalization.scale) | |
| and other.training_system_ids == self.normalization.training_system_ids | |
| ): | |
| raise ValueError("Ensemble normalization artifacts differ") | |
| configs = [c["model_config"] for c in self.checkpoints] | |
| self.history_steps = int(configs[0].get("history_steps", 24)) | |
| self.future_steps = int(configs[0].get("future_steps", 8)) | |
| if any( | |
| c.get("history_steps", 24) != self.history_steps or c.get("future_steps", 8) != self.future_steps | |
| for c in configs | |
| ): | |
| raise ValueError("Ensemble temporal configurations differ") | |
| self.specs, self.index = FIELD_SPECS, FIELD_INDEX | |
| self.calibration = None | |
| if calibration: | |
| data = json.loads(Path(calibration).read_text()) | |
| if set(data.get("checkpoint_sha256", [])) != set(self.hashes): | |
| raise ValueError("Calibration must identify exactly the loaded checkpoint weights") | |
| if data.get("nominal_coverage") != 0.9: | |
| raise ValueError("Only nominal 90% calibration supported") | |
| normalization_hash = hashlib.sha256( | |
| (Path(checkpoints[0]).parent / "normalization.json").read_bytes() | |
| ).hexdigest() | |
| if data.get("normalization_sha256") != normalization_hash: | |
| raise ValueError("Calibration normalization artifact mismatch") | |
| from tfm.evaluation.calibration import validate_calibration | |
| forbidden = set() | |
| for checkpoint in self.checkpoints: | |
| for key in ("training_system_ids", "validation_selection_system_ids", "test_system_ids"): | |
| forbidden.update(checkpoint.get(key, [])) | |
| validate_calibration( | |
| data, | |
| checkpoint_sha256=self.hashes, | |
| normalization_version=1, | |
| normalization_sha256=normalization_hash, | |
| forbidden_system_ids=forbidden, | |
| ) | |
| if not data.get("calibration_system_ids"): | |
| raise ValueError("Calibration artifact lacks held-out system provenance") | |
| reserved = set.intersection(*(set(c.get("calibration_system_ids", [])) for c in self.checkpoints)) | |
| if not set(data["calibration_system_ids"]) <= reserved: | |
| raise ValueError("Calibration systems were not reserved by the trained checkpoint") | |
| self.calibration = data | |
| def _validate(self, req: PredictRequest): | |
| from tfm.data.schema import SCHEMAS | |
| fields = {f.name: f for f in req.system_schema.fields} | |
| if len(fields) != len(req.system_schema.fields): | |
| raise ValueError("Duplicate schema fields") | |
| names = set(fields) | |
| if names != set(SCHEMAS[req.system_schema.family]): | |
| # Thermal one-node schema explicitly omits only mass_temp. | |
| if req.system_schema.family != "thermal" or names != set(SCHEMAS["thermal"]) - {"mass_temp"}: | |
| raise ValueError("Schema must match a supported family configuration") | |
| for name, metadata in fields.items(): | |
| if name not in self.index: | |
| raise ValueError(f"Unknown field {name}; map to the controlled vocabulary") | |
| spec = self.specs[self.index[name]] | |
| if metadata.unit != spec.unit or metadata.role != spec.role: | |
| raise ValueError(f"Unknown or incompatible unit/role for {name}") | |
| if metadata.minimum is not None and not spec.minimum <= metadata.minimum <= spec.maximum: | |
| raise ValueError(f"Permissible range cannot exceed supported range for {name}") | |
| if metadata.maximum is not None and not spec.minimum <= metadata.maximum <= spec.maximum: | |
| raise ValueError(f"Permissible range cannot exceed supported range for {name}") | |
| if ( | |
| metadata.minimum is not None | |
| and metadata.maximum is not None | |
| and metadata.minimum > metadata.maximum | |
| ): | |
| raise ValueError(f"Invalid range for {name}") | |
| roles = { | |
| role: {name for name in names if fields[name].role == role} | |
| for role in ("state", "action", "exogenous") | |
| } | |
| if len(set(req.predict)) != len(req.predict) or not set(req.predict) <= roles["state"]: | |
| raise ValueError("Requested predictions must be unique active state fields") | |
| if len(set(req.horizons_minutes)) != len(req.horizons_minutes): | |
| raise ValueError("Duplicate horizons") | |
| if any(h not in (15, 30, 60, 120) or h > self.future_steps * 15 for h in req.horizons_minutes): | |
| raise ValueError("Supported horizons are 15, 30, 60, 120 minutes within trained action horizon") | |
| def values(mapping, role, allow_missing=False): | |
| if set(mapping) != roles[role]: | |
| raise ValueError(f"Expected exactly {sorted(roles[role])} for {role}") | |
| for name, value in mapping.items(): | |
| if value is None and allow_missing: | |
| continue | |
| sequence = value if isinstance(value, list) else [value] | |
| spec = self.specs[self.index[name]] | |
| lo = fields[name].minimum if fields[name].minimum is not None else spec.minimum | |
| hi = fields[name].maximum if fields[name].maximum is not None else spec.maximum | |
| if any(v is None or not np.isfinite(v) or v < lo or v > hi for v in sequence): | |
| raise ValueError(f"Invalid physical value for {name}; expected [{lo}, {hi}]") | |
| values(req.state, "state", True) | |
| if any(req.state[f] is None for f in req.predict): | |
| raise ValueError("Requested fields require an observed current value for delta decoding") | |
| for seq in req.actions.values(): | |
| values(seq, "action") | |
| if any(len(s) != self.future_steps for s in seq.values()): | |
| raise ValueError(f"Action sequences require {self.future_steps} steps") | |
| values(req.exogenous, "exogenous") | |
| if any(len(s) != self.future_steps for s in req.exogenous.values()): | |
| raise ValueError(f"Exogenous sequences require {self.future_steps} steps") | |
| if len(req.history) > self.history_steps: | |
| raise ValueError(f"Checkpoint accepts at most {self.history_steps} history observations") | |
| times = [float(h.timestamp_minutes) for h in req.history] | |
| if times and (times[-1] != 0 or any(abs(b - a - 15) > 1e-6 for a, b in zip(times, times[1:]))): | |
| raise ValueError("History timestamps must be spaced 15 minutes apart and end at 0 (current time)") | |
| for i, obs in enumerate(req.history): | |
| values(obs.state, "state", True) | |
| if i < len(req.history) - 1: | |
| values(obs.actions, "action") | |
| values(obs.exogenous, "exogenous") | |
| elif obs.actions or obs.exogenous: | |
| raise ValueError( | |
| "Current observation has no already-applied future action or exogenous input" | |
| ) | |
| if req.history and req.history[-1].state != req.state: | |
| raise ValueError("Final history state must equal current state") | |
| return fields | |
| def prepare(self, req: PredictRequest): | |
| from tfm.data.schema import ROLE_IDS, UNIT_IDS | |
| fields = self._validate(req) | |
| f_count = len(self.specs) | |
| h_count = self.history_steps | |
| history = np.zeros((h_count, f_count), np.float32) | |
| mask = np.zeros_like(history) | |
| current = np.zeros(f_count, np.float32) | |
| current_mask = np.zeros(f_count, np.float32) | |
| field_mask = np.zeros(f_count, bool) | |
| for name in fields: | |
| field_mask[self.index[name]] = True | |
| for name, value in req.state.items(): | |
| if value is not None: | |
| i = self.index[name] | |
| current[i] = (value - self.normalization.mean[i]) / self.normalization.scale[i] | |
| current_mask[i] = 1 | |
| observations = req.history or [Observation(timestamp_minutes=0, state=req.state)] | |
| offset = h_count - len(observations) | |
| for row, obs in enumerate(observations, offset): | |
| for mapping in (obs.state, obs.actions, obs.exogenous): | |
| for name, value in mapping.items(): | |
| if value is not None: | |
| i = self.index[name] | |
| history[row, i] = (value - self.normalization.mean[i]) / self.normalization.scale[i] | |
| mask[row, i] = 1 | |
| query_fields = [self.index[name] for name in req.predict for _ in req.horizons_minutes] | |
| query_horizons = req.horizons_minutes * len(req.predict) | |
| def sequence(mapping): | |
| arr = np.zeros((self.future_steps, f_count), np.float32) | |
| for name, seq in mapping.items(): | |
| i = self.index[name] | |
| arr[:, i] = (np.array(seq) - self.normalization.mean[i]) / self.normalization.scale[i] | |
| return arr | |
| shared = dict( | |
| history=history, | |
| history_mask=mask, | |
| history_dt=np.arange(-h_count + 1, 1, dtype=np.float32) * 15, | |
| current=current, | |
| current_mask=current_mask, | |
| field_mask=field_mask, | |
| field_ids=np.arange(f_count, dtype=np.int64), | |
| unit_ids=np.asarray(UNIT_IDS, np.int64), | |
| role_ids=np.asarray(ROLE_IDS, np.int64), | |
| future_exogenous=sequence(req.exogenous), | |
| future_dt=np.arange(1, self.future_steps + 1, dtype=np.float32) * 15, | |
| query_fields=np.array(query_fields, np.int64), | |
| query_horizons=np.array(query_horizons, np.float32), | |
| ) | |
| batches = [{**shared, "future_actions": sequence(action)} for action in req.actions.values()] | |
| batch = {k: torch.from_numpy(np.stack([b[k] for b in batches])).to(self.device) for k in shared} | |
| batch["future_actions"] = torch.from_numpy(np.stack([b["future_actions"] for b in batches])).to( | |
| self.device | |
| ) | |
| return batch, fields | |
| def predict(self, req: PredictRequest) -> PredictResponse: | |
| batch, fields = self.prepare(req) | |
| predictions = [model(batch) for model in self.models] | |
| means = torch.stack([p[0] for p in predictions]) | |
| variances = torch.stack([p[1].exp().square() for p in predictions]) | |
| mean = means.mean(0) | |
| std = (variances.mean(0) + means.var(0, unbiased=False)).clamp_min(1e-12).sqrt() | |
| mean, std = mean.cpu().numpy(), std.cpu().numpy() | |
| if not np.isfinite(mean).all() or not np.isfinite(std).all(): | |
| raise RuntimeError("Model produced nonfinite predictions") | |
| result = {} | |
| for a, label in enumerate(req.actions): | |
| result[label] = {} | |
| for j, name in enumerate(req.predict): | |
| i = self.index[name] | |
| spec = self.specs[i] | |
| lo = fields[name].minimum if fields[name].minimum is not None else spec.minimum | |
| hi = fields[name].maximum if fields[name].maximum is not None else spec.maximum | |
| for k, horizon in enumerate(req.horizons_minutes): | |
| q = j * len(req.horizons_minutes) + k | |
| raw = float(req.state[name] + mean[a, q] * self.normalization.scale[i]) | |
| sigma = float(std[a, q] * self.normalization.scale[i]) | |
| estimate = float(np.clip(raw, lo, hi)) | |
| entry = (self.calibration or {}).get("entries", {}).get(f"{i}:{horizon:g}") | |
| interval = None | |
| if entry is not None and entry.get("multiplier") is not None: | |
| multiplier = float(entry["multiplier"]) | |
| if not np.isfinite(multiplier) or multiplier < 0: | |
| raise RuntimeError("Invalid calibration multiplier") | |
| # Preserve the calibrated raw center; clipping intersects physical support. | |
| interval = ( | |
| float(np.clip(raw - multiplier * sigma, lo, hi)), | |
| float(np.clip(raw + multiplier * sigma, lo, hi)), | |
| ) | |
| result[label].setdefault(str(horizon), {})[name] = FieldPrediction( | |
| mean=estimate, | |
| predictive_std=sigma, | |
| interval_90=interval, | |
| interval_status="calibrated" if interval else "unavailable", | |
| physically_clipped=estimate != raw, | |
| ) | |
| state_values = batch["current"] | |
| state_mask = batch["current_mask"].bool() | |
| ood = bool(((state_values.abs() > 6) & state_mask).any().cpu()) | |
| return PredictResponse( | |
| model_version=self.version, | |
| predictions=result, | |
| indicators={ | |
| "insufficient_context": len(req.history) < self.history_steps, | |
| "out_of_distribution": ood, | |
| "ood_method": "heuristic: current observed states beyond six training standard deviations", | |
| "intervals_condition_on_known_exogenous": True, | |
| "missing_observations": bool( | |
| (batch["history_mask"][0, :, batch["field_mask"][0]].sum(0) == 0).any().cpu() | |
| ), | |
| }, | |
| ) | |
| def create_app(engine: PredictionEngine | None = None) -> FastAPI: | |
| app = FastAPI(title="Transition Foundation Model", version="0.1.0") | |
| app.state.engine = engine | |
| def health(): | |
| return {"status": "ready" if app.state.engine is not None else "unconfigured"} | |
| def predict(req: PredictRequest): | |
| if app.state.engine is None: | |
| raise HTTPException(503, "Configure TFM_CHECKPOINT with trained weights") | |
| try: | |
| return app.state.engine.predict(req) | |
| except ValueError as exc: | |
| raise HTTPException(422, str(exc)) from exc | |
| return app | |
| def configured_app(): | |
| checkpoints = [s for s in os.environ.get("TFM_CHECKPOINT", "").split(",") if s] | |
| engine = ( | |
| PredictionEngine(checkpoints, os.environ.get("TFM_CALIBRATION"), os.environ.get("TFM_DEVICE", "cpu")) | |
| if checkpoints | |
| else None | |
| ) | |
| return create_app(engine) | |
| app = configured_app() | |