single-sensor-outage-imputer 0.1.0__py3-none-any.whl

single_sensor_outage_imputer-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: single-sensor-outage-imputer
+Version: 0.1.0
+Summary: TCDR runtime for single-sensor outage target imputation
+Project-URL: Repository, https://github.com/romulobrito/single-sensor-outage-imputer
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: torch>=1.9.0
+Requires-Dist: joblib>=1.0.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: hdf5
+Requires-Dist: tables>=3.8; extra == "hdf5"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# Single-sensor outage imputer
+
+Runtime package for **single-sensor outage recovery**: reconstruct one target tag
+when it is unavailable while auxiliary sensors remain online.
+
+The model is a **target-conditional denoising regressor (TCDR)**:
+
+```text
+input  = [x ; t_tilde ; m_t]
+output = t_hat   (scalar)
+```
+
+At deployment, outage mode is forced as:
+
+```text
+[t_tilde, m_t] = [0, 1]   (0 in standardized target space = train mean)
+t_hat = f_theta(x, 0, 1)
+```
+
+This repository is the **offline training and inference** surface (`VirtualSensor`,
+bundle I/O). The **host** for outage recovery is BibMon: it consumes SSOI as an
+optional extra. Canonical integration spec:
+
+- `../BibMon/doc/SSOI_BIBMON.md` (workspace) or BibMon `doc/SSOI_BIBMON.md`
+- Roadmap in this repo: `doc/PLANO_INTEGRACAO_BIBMON.md`
+
+The research manuscript, controlled MCAR/MAR/MNAR validation, and baselines live
+in a separate lab repo.
+
+## Install
+
+```bash
+git clone https://github.com/romulobrito/single-sensor-outage-imputer.git
+cd single-sensor-outage-imputer
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e ".[dev]"
+```
+
+HDF5 training needs PyTables:
+
+```bash
+pip install -e ".[hdf5,dev]"
+```
+
+## Quick start (synthetic smoke)
+
+```bash
+python examples/smoke_synthetic.py
+```
+
+This fits scalers on synthetic data, trains a tiny TCDR, writes a bundle under
+`examples/synthetic_bundle/`, reloads it, and runs `predict`.
+
+## Train from scratch on local industrial data
+
+Keep the historian file **outside git** (or under ignored `data/`). Example:
+
+```bash
+python examples/train_from_h5.py \
+  --data /path/to/sulfatos_dados_concatenados_formatados_2021.h5 \
+  --target 1251_FIT_801C_2 \
+  --bundle-dir artifacts/bundle_target_a \
+  --hdf-key optional_table_name
+```
+
+Omit `--cpu` to use CUDA when available. `--hdf-key` is only required when the
+HDF5 file contains more than one table.
+
+To keep an auxiliary out of automatic screening even if correlation is high:
+
+```bash
+python examples/train_from_h5.py \
+  --data /path/to/data.h5 \
+  --target 1251_FIT_801C_2 \
+  --bundle-dir artifacts/bundle_target_a \
+  --exclude-features TAG_INSTAVEL \
+  --exclude-features-file plant_exclude.json
+```
+
+`--exclude-features` and the JSON file are merged. The JSON may be a list or
+`{"exclude_features": ["TAG_INSTAVEL"]}`. Screening still ranks the remaining
+columns. The banned names are stored in the bundle as `excluded_features`
+(audit only; inference uses `selected_features`).
+
+HDF5 screening tests skip unless `SSOI_H5_PATH` or `data/*.h5` exists. They
+do not train a full TCDR and do not print process values.
+
+This runs blocked chronological split with adaptive head-skip, train-only
+feature screening, mask-weighted TCDR training, bundle export, and held-out
+outage-mode metrics via `VirtualSensor.predict`.
+
+Several targets at once: one process per target, started together by
+`examples/train_parallel.py` (JSON job list, `max_parallel` cap). See
+`examples/train_parallel.example.json`. Each job still needs its own
+`bundle_dir`.
+
+## Ecosystem integration
+
+```python
+from ssoi import VirtualSensor
+
+sensor = VirtualSensor.from_bundle("path/to/bundle")
+y_hat = sensor.predict(X_dataframe_or_ndarray)
+```
+
+### Bundle contract
+
+A bundle directory must contain:
+
+| File | Role |
+|------|------|
+| `manifest.json` | metadata / schema version |
+| `feature_selection_config.json` | ordered auxiliary feature names |
+| `train_feature_means.json` | train-only fill values for NaNs in `x` |
+| `scaler_X.joblib` | feature scaler fitted on train |
+| `scaler_y.joblib` | target scaler fitted on train |
+| `model_config.json` | architecture hyperparameters |
+| `best_model.pth` | trained weights |
+
+### Input / output
+
+- **Input:** auxiliaries in the feature order from the bundle (DataFrame columns
+  or `ndarray` with shape `(n, n_features)`).
+- **Output:** `t_hat` in engineering units (inverse-scaled).
+- **Missing auxiliaries:** filled with train means, then `0.0` as fallback.
+- **Target channel:** always treated as missing at inference (`m_t=1`).
+- **Batching:** `predict(..., batch_size=1024)` slices the forward pass (override as needed).
+
+## Not in scope here
+
+- Industrial raw historian dumps
+- Paper LaTeX / figure pipelines
+- Full Phase-2 mechanism stress tests
+
+Train offline in your environment, publish the **bundle**, and call this package
+only for inference (or for lightweight retrain scripts you add later).
+
+## License / authorship
+
+Research context: UFRJ industrial virtual-sensing work. Adapt target names and
+feature lists to your plant tags.

single_sensor_outage_imputer-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ssoi/__init__.py,sha256=cyk84kTQIsyDy5-ok-YfE5jizpVhieHJcXeqB3fbdQU,661
+ssoi/bundle.py,sha256=S82o3buxAeX3MauHd2g9grFa1L7Z3XLhfoF0K8-TBJY,7615
+ssoi/model.py,sha256=D_AaSa_3cCvGzd5LdGelxAtYPFq9Wb3q3juYmLnGxZo,3598
+ssoi/predict.py,sha256=DuflyYd4tqw1CsNw6uJ3yhOzrQd8m6sHAtsDe4dttFU,5228
+ssoi/train.py,sha256=4UsTcIKgi-qgedjqCeAMPHj4Jio3oa9ExIu9LJM7EfM,23727
+ssoi/train_jobs.py,sha256=NSDjBzjbOKrxCK02Z1v4w2rB-4sMhxjDTzPRVAnAEN8,11406
+single_sensor_outage_imputer-0.1.0.dist-info/METADATA,sha256=N_oUv9pBM3nOxELWoqs8rKcLwrd49s2sBhxsHKTuR-Q,5168
+single_sensor_outage_imputer-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+single_sensor_outage_imputer-0.1.0.dist-info/top_level.txt,sha256=UrrLdnOMSq7TIpY0LPQZAyUuwJgpfBsWBWE84YO6Wkk,5
+single_sensor_outage_imputer-0.1.0.dist-info/RECORD,,

single_sensor_outage_imputer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

single_sensor_outage_imputer-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ssoi

ssoi/__init__.py

@@ -0,0 +1,24 @@
+"""
+Single-sensor outage imputer (SSOI).
+
+Runtime package for target-conditional denoising regressor (TCDR) inference
+under the deployment pattern: auxiliaries observed, target unavailable.
+"""
+from __future__ import annotations
+
+from ssoi.bundle import ImputerBundle, load_bundle, save_bundle
+from ssoi.model import TargetConditionalDenoisingRegressor
+from ssoi.predict import VirtualSensor
+from ssoi.train import train_from_dataframe, train_from_h5
+
+__all__ = [
+    "ImputerBundle",
+    "TargetConditionalDenoisingRegressor",
+    "VirtualSensor",
+    "load_bundle",
+    "save_bundle",
+    "train_from_dataframe",
+    "train_from_h5",
+]
+
+__version__ = "0.1.0"

ssoi/bundle.py

@@ -0,0 +1,235 @@
+"""
+Bundle I/O for deployment artifacts.
+
+A bundle is a directory containing:
+  - manifest.json
+  - feature_selection_config.json  (feature column order)
+  - train_feature_means.json       (per-feature fill values)
+  - scaler_X.joblib / scaler_y.joblib
+  - model_config.json
+  - best_model.pth
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+import joblib
+import numpy as np
+import torch
+from sklearn.preprocessing import StandardScaler
+
+from ssoi.model import TargetConditionalDenoisingRegressor
+
+PathLike = Union[str, Path]
+
+
+@dataclass
+class ImputerBundle:
+    """In-memory deployment bundle for single-sensor outage imputation."""
+
+    features: List[str]
+    train_feature_means: Dict[str, float]
+    scaler_x: Any
+    scaler_y: Any
+    model: TargetConditionalDenoisingRegressor
+    target_name: str
+    manifest: Dict[str, Any]
+    model_config: Dict[str, Any]
+
+
+def _read_json(path: Path) -> Dict[str, Any]:
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected JSON object in {path}")
+    return data
+
+
+def _write_json(path: Path, payload: Mapping[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as fh:
+        json.dump(dict(payload), fh, indent=2, sort_keys=True)
+        fh.write("\n")
+
+
+def _extract_feature_list(feature_cfg: Mapping[str, Any]) -> List[str]:
+    """Accept common feature-config layouts used in the research pipeline."""
+    if "selected_features" in feature_cfg:
+        feats = feature_cfg["selected_features"]
+    elif "features" in feature_cfg:
+        feats = feature_cfg["features"]
+    else:
+        raise KeyError(
+            "feature_selection_config.json must contain "
+            "'selected_features' or 'features'"
+        )
+    if not isinstance(feats, list) or not feats:
+        raise ValueError("Feature list must be a non-empty list of strings")
+    out: List[str] = []
+    for item in feats:
+        if not isinstance(item, str) or not item:
+            raise ValueError(f"Invalid feature name: {item!r}")
+        out.append(item)
+    return out
+
+
+def _means_to_dict(
+    features: List[str],
+    means_raw: Mapping[str, Any],
+) -> Dict[str, float]:
+    """Normalize means JSON to feature -> float."""
+    # Allow {"means": {...}} or flat {feature: value}
+    if "means" in means_raw and isinstance(means_raw["means"], dict):
+        source = means_raw["means"]
+    else:
+        source = means_raw
+    out: Dict[str, float] = {}
+    for name in features:
+        if name not in source:
+            raise KeyError(f"Missing train mean for feature '{name}'")
+        out[name] = float(source[name])
+    return out
+
+
+def save_bundle(
+    bundle_dir: PathLike,
+    *,
+    features: List[str],
+    train_feature_means: Mapping[str, float],
+    scaler_x: Any,
+    scaler_y: Any,
+    model: TargetConditionalDenoisingRegressor,
+    target_name: str,
+    manifest: Optional[Mapping[str, Any]] = None,
+    excluded_features: Optional[Sequence[str]] = None,
+) -> Path:
+    """
+    Persist a trainable/deployable bundle to disk.
+
+    Returns the bundle directory path.
+    """
+    root = Path(bundle_dir)
+    root.mkdir(parents=True, exist_ok=True)
+
+    excluded = [str(name) for name in (excluded_features or []) if str(name)]
+    feature_cfg = {
+        "selected_features": list(features),
+        "target": target_name,
+        "excluded_features": excluded,
+    }
+    means_payload = {"means": {k: float(v) for k, v in train_feature_means.items()}}
+    model_cfg = model.config_dict()
+    man = {
+        "schema_version": "1.0",
+        "package": "single-sensor-outage-imputer",
+        "target_name": target_name,
+        "n_features": len(features),
+        "inference_mode": "missing_target",
+        "inference_channels": {"t_tilde": 0.0, "m_t": 1.0},
+        "excluded_features": excluded,
+    }
+    if manifest:
+        man.update(dict(manifest))
+    man["excluded_features"] = excluded
+
+    _write_json(root / "feature_selection_config.json", feature_cfg)
+    _write_json(root / "train_feature_means.json", means_payload)
+    _write_json(root / "model_config.json", model_cfg)
+    _write_json(root / "manifest.json", man)
+    joblib.dump(scaler_x, root / "scaler_X.joblib")
+    joblib.dump(scaler_y, root / "scaler_y.joblib")
+    torch.save(model.state_dict(), root / "best_model.pth")
+    return root
+
+
+def load_bundle(bundle_dir: PathLike, device: str = "cpu") -> ImputerBundle:
+    """
+    Load a deployment bundle from disk.
+
+    Args:
+        bundle_dir: directory with manifest, scalers, and weights
+        device: torch device string for the loaded model
+    """
+    root = Path(bundle_dir)
+    if not root.is_dir():
+        raise FileNotFoundError(f"Bundle directory not found: {root}")
+
+    required = [
+        "manifest.json",
+        "feature_selection_config.json",
+        "train_feature_means.json",
+        "model_config.json",
+        "scaler_X.joblib",
+        "scaler_y.joblib",
+        "best_model.pth",
+    ]
+    missing = [name for name in required if not (root / name).exists()]
+    if missing:
+        raise FileNotFoundError(f"Bundle incomplete at {root}: missing {missing}")
+
+    manifest = _read_json(root / "manifest.json")
+    feature_cfg = _read_json(root / "feature_selection_config.json")
+    means_raw = _read_json(root / "train_feature_means.json")
+    model_cfg = _read_json(root / "model_config.json")
+
+    features = _extract_feature_list(feature_cfg)
+    means = _means_to_dict(features, means_raw)
+    target_name = str(
+        manifest.get("target_name")
+        or feature_cfg.get("target")
+        or "target"
+    )
+
+    n_features = int(model_cfg.get("n_features", len(features)))
+    if n_features != len(features):
+        raise ValueError(
+            f"model_config n_features={n_features} != len(features)={len(features)}"
+        )
+    latent_dim = int(model_cfg.get("latent_dim", 16))
+    dropout = float(model_cfg.get("dropout", 0.2))
+
+    model = TargetConditionalDenoisingRegressor(
+        n_features=n_features,
+        latent_dim=latent_dim,
+        dropout=dropout,
+    )
+    weights_path = root / "best_model.pth"
+    try:
+        state = torch.load(weights_path, map_location=device)
+        model.load_state_dict(state)
+    except FileNotFoundError:
+        raise
+    except Exception as exc:
+        raise RuntimeError(
+            f"Failed to load model weights from {weights_path}: {exc}"
+        ) from exc
+    model.to(device)
+    model.eval()
+
+    scaler_x = joblib.load(root / "scaler_X.joblib")
+    scaler_y = joblib.load(root / "scaler_y.joblib")
+    if not isinstance(scaler_x, StandardScaler):
+        # Accept RobustScaler or other sklearn transformers with transform()
+        if not hasattr(scaler_x, "transform"):
+            raise TypeError("scaler_X must expose .transform()")
+    n_in = getattr(scaler_x, "n_features_in_", None)
+    if n_in is not None and int(n_in) != len(features):
+        raise ValueError(
+            f"scaler_X n_features_in_={int(n_in)} != len(features)={len(features)}"
+        )
+    if not hasattr(scaler_y, "inverse_transform"):
+        raise TypeError("scaler_y must expose .inverse_transform()")
+
+    return ImputerBundle(
+        features=features,
+        train_feature_means=means,
+        scaler_x=scaler_x,
+        scaler_y=scaler_y,
+        model=model,
+        target_name=target_name,
+        manifest=manifest,
+        model_config=model_cfg,
+    )

ssoi/model.py

@@ -0,0 +1,114 @@
+"""
+TCDR network: target-conditional denoising regressor.
+
+Maps observability-aware input [x; t_tilde; m_t] to scalar target estimate.
+Extracted from the paper research implementation (ConditionalDenoisingAE).
+"""
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+import torch
+import torch.nn as nn
+
+
+def tcdr_hidden_widths(n_features: int, latent_dim: int = 16) -> Tuple[int, int, int]:
+    """
+    Compute hidden widths from auxiliary feature count.
+
+    Capacity uses in_dim = n_features + 2 (x plus t_tilde and m_t), matching
+    the manuscript sizing rule.
+    """
+    if n_features < 1:
+        raise ValueError(f"n_features must be >= 1, got {n_features}")
+    capacity_in_dim = int(n_features) + 2
+    h1 = max(64, 8 * capacity_in_dim)
+    h2 = max(32, 4 * capacity_in_dim)
+    return h1, h2, int(latent_dim)
+
+
+class TargetConditionalDenoisingRegressor(nn.Module):
+    """
+    Supervised scalar regressor for single-sensor outage recovery.
+
+    Input channels:
+      - x: auxiliary sensors (n_features)
+      - t_tilde: observed target or 0 when missing (scaled space)
+      - m_t: 1 if target unavailable, 0 if observed
+
+    Output:
+      - t_hat: predicted target in the same scaled space as training
+    """
+
+    def __init__(
+        self,
+        n_features: int,
+        latent_dim: int = 16,
+        dropout: float = 0.2,
+    ) -> None:
+        super().__init__()
+        if n_features < 1:
+            raise ValueError(f"n_features must be >= 1, got {n_features}")
+        self.n_features = int(n_features)
+        self.latent_dim = int(latent_dim)
+        self.dropout = float(dropout)
+        h1, h2, latent = tcdr_hidden_widths(self.n_features, self.latent_dim)
+        self.h1 = h1
+        self.h2 = h2
+        in_dim = self.n_features + 2
+        self.net = nn.Sequential(
+            nn.Linear(in_dim, h1),
+            nn.BatchNorm1d(h1),
+            nn.LeakyReLU(0.1),
+            nn.Dropout(self.dropout),
+            nn.Linear(h1, h2),
+            nn.BatchNorm1d(h2),
+            nn.LeakyReLU(0.1),
+            nn.Dropout(self.dropout / 2.0),
+            nn.Linear(h2, latent),
+            nn.BatchNorm1d(latent),
+            nn.LeakyReLU(0.1),
+            nn.Linear(latent, h2),
+            nn.LeakyReLU(0.1),
+            nn.Linear(h2, 1),
+        )
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        t_tilde: torch.Tensor,
+        m_t: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Forward pass.
+
+        Args:
+            x: shape (batch, n_features)
+            t_tilde: shape (batch, 1)
+            m_t: shape (batch, 1)
+        """
+        if x.ndim != 2:
+            raise ValueError(f"x must be 2D (batch, n_features), got shape {tuple(x.shape)}")
+        if x.shape[1] != self.n_features:
+            raise ValueError(
+                f"x has {x.shape[1]} features, model expects {self.n_features}"
+            )
+        inp = torch.cat([x, t_tilde, m_t], dim=1)
+        return self.net(inp)
+
+    def parameter_count(self) -> int:
+        """Return number of trainable parameters."""
+        return int(sum(p.numel() for p in self.parameters() if p.requires_grad))
+
+    def config_dict(self) -> Dict[str, object]:
+        """Serializable architecture metadata for bundle manifests."""
+        return {
+            "model_type": "tcdr",
+            "n_features": self.n_features,
+            "in_dim": self.n_features + 2,
+            "h1": self.h1,
+            "h2": self.h2,
+            "latent_dim": self.latent_dim,
+            "dropout": self.dropout,
+            "parameter_count": self.parameter_count(),
+        }

ssoi/predict.py

@@ -0,0 +1,145 @@
+"""
+Inference API for single-sensor outage virtual sensing.
+
+Deployment pattern: auxiliaries available, target missing
+  t_hat = f_theta(x_scaled, t_tilde=0, m_t=1)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+import torch
+
+from ssoi.bundle import ImputerBundle, load_bundle
+
+ArrayLike = Union[np.ndarray, pd.DataFrame, Sequence[Sequence[float]]]
+PathLike = Union[str, Path]
+
+
+class VirtualSensor:
+    """
+    Load a TCDR bundle and impute the target under outage conditions.
+    """
+
+    def __init__(self, bundle: ImputerBundle, device: str = "cpu") -> None:
+        self.bundle = bundle
+        self.device = device
+        self.bundle.model.to(device)
+        self.bundle.model.eval()
+
+    @classmethod
+    def from_bundle(cls, bundle_dir: PathLike, device: str = "cpu") -> "VirtualSensor":
+        """Construct from a bundle directory path."""
+        return cls(load_bundle(bundle_dir, device=device), device=device)
+
+    @property
+    def features(self) -> List[str]:
+        """Ordered auxiliary feature names required at inference."""
+        return list(self.bundle.features)
+
+    @property
+    def target_name(self) -> str:
+        """Name of the reconstructed target tag."""
+        return self.bundle.target_name
+
+    def _frame_from_input(self, x: ArrayLike) -> pd.DataFrame:
+        """Normalize caller input to a DataFrame with expected columns."""
+        if isinstance(x, pd.DataFrame):
+            missing = [c for c in self.features if c not in x.columns]
+            if missing:
+                raise KeyError(f"Input DataFrame missing columns: {missing}")
+            return x.loc[:, self.features].copy()
+
+        arr = np.asarray(x, dtype=np.float64)
+        if arr.ndim == 1:
+            arr = arr.reshape(1, -1)
+        if arr.ndim != 2:
+            raise ValueError(f"Expected 2D feature array, got shape {arr.shape}")
+        if arr.shape[1] != len(self.features):
+            raise ValueError(
+                f"Expected {len(self.features)} features, got {arr.shape[1]}"
+            )
+        return pd.DataFrame(arr, columns=self.features)
+
+    def _impute_auxiliaries(self, frame: pd.DataFrame) -> np.ndarray:
+        """Fill NaNs in auxiliaries using train-only means, then zeros."""
+        means = self.bundle.train_feature_means
+        filled = frame.copy()
+        for col in self.features:
+            filled[col] = filled[col].fillna(means[col])
+        filled = filled.fillna(0.0)
+        return filled.to_numpy(dtype=np.float64)
+
+    def predict(
+        self,
+        x: ArrayLike,
+        *,
+        return_scaled: bool = False,
+        batch_size: int = 1024,
+    ) -> np.ndarray:
+        """
+        Predict target values in outage mode (m_t=1, t_tilde=0).
+
+        Args:
+            x: DataFrame with feature columns, or ndarray (n, n_features)
+            return_scaled: if True, return predictions in scaled target space
+            batch_size: max rows per forward pass (must be >= 1)
+
+        Returns:
+            1D numpy array of predictions (engineering units by default)
+        """
+        if int(batch_size) < 1:
+            raise ValueError(f"batch_size must be >= 1, got {batch_size}")
+        frame = self._frame_from_input(x)
+        x_raw = self._impute_auxiliaries(frame)
+        x_scaled = self.bundle.scaler_x.transform(x_raw).astype(np.float32)
+
+        n = int(x_scaled.shape[0])
+        chunks: List[np.ndarray] = []
+        step = int(batch_size)
+        self.bundle.model.eval()
+        with torch.no_grad():
+            for start in range(0, n, step):
+                stop = min(start + step, n)
+                x_t = torch.from_numpy(x_scaled[start:stop]).to(self.device)
+                rows = int(x_t.shape[0])
+                t_zero = torch.zeros((rows, 1), dtype=torch.float32, device=self.device)
+                m_one = torch.ones((rows, 1), dtype=torch.float32, device=self.device)
+                y_hat_scaled = self.bundle.model(x_t, t_zero, m_one).cpu().numpy()
+                chunks.append(y_hat_scaled.reshape(-1))
+
+        if chunks:
+            y_hat_scaled = np.concatenate(chunks, axis=0)
+        else:
+            y_hat_scaled = np.empty((0,), dtype=np.float32)
+
+        if return_scaled:
+            return y_hat_scaled.reshape(-1)
+
+        y_hat = self.bundle.scaler_y.inverse_transform(y_hat_scaled.reshape(-1, 1))
+        return y_hat.reshape(-1)
+
+    def predict_dict_rows(
+        self,
+        rows: Sequence[Mapping[str, Any]],
+    ) -> List[float]:
+        """
+        Convenience API for ecosystem messages: list of feature dicts -> list of floats.
+        """
+        frame = pd.DataFrame(list(rows))
+        preds = self.predict(frame)
+        return [float(v) for v in preds]
+
+    def info(self) -> Dict[str, Any]:
+        """Return a small status dict useful for health checks."""
+        return {
+            "target_name": self.target_name,
+            "n_features": len(self.features),
+            "features": self.features,
+            "device": self.device,
+            "manifest": dict(self.bundle.manifest),
+            "parameter_count": self.bundle.model.parameter_count(),
+        }