File size: 18,168 Bytes
1baf215
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
"""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

    @torch.inference_mode()
    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

    @app.get("/health")
    def health():
        return {"status": "ready" if app.state.engine is not None else "unconfigured"}

    @app.post("/v1/predict", response_model=PredictResponse)
    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()