BijliCast / service.py
muhammadumar15's picture
Add service.py
3d38b29 verified
Raw History Blame Contribute Delete
9.74 kB
"""Shared inference service for the BijliCast deployments.
Both the FastAPI backend and the Streamlit UI use one contract:
household profile
+ the last 168 hourly usage values for that house
+ current-hour weather
+ the origin timestamp
-> build_inference_row -> deployment_model.joblib -> next-hour kWh
Keeping this out of the web frameworks means the API, the Streamlit app and
the Hugging Face Space cannot drift apart.
"""
from __future__ import annotations
import json
from dataclasses import asdict, dataclass, field
from functools import lru_cache
from pathlib import Path
import joblib
import numpy as np
import pandas as pd
from src.features.inference import build_inference_row
from src.utils.config import (
CITY_COL,
HOUSE_COL,
INPUT_WEATHER_FEATURES,
STATIC_CATEGORICAL_FEATURES,
STATIC_NUMERIC_FEATURES,
TIME_COL,
)
REQUIRED_ARTIFACTS = (
"deployment_model.joblib",
"house_profiles.csv",
"usage_history.parquet",
"latest_weather.csv",
"model_metadata.json",
"app_manifest.json",
)
class BijliCastError(RuntimeError):
"""Base error for the deployment service."""
class ArtifactsMissingError(BijliCastError):
"""Raised when the committed deployment bundle is incomplete."""
class UnknownHouseError(BijliCastError):
"""Raised when a request names a household that is not in the bundle."""
def _finite(value) -> float | None:
"""JSON-safe float: NaN/inf become None."""
number = float(value)
return number if np.isfinite(number) else None
def _profile_payload(profile: pd.Series) -> dict:
"""Small, JSON-safe profile block shown by the apps."""
out: dict = {}
for col in STATIC_NUMERIC_FEATURES:
out[col] = _finite(profile[col])
for col in STATIC_CATEGORICAL_FEATURES:
value = profile[col]
out[col] = None if pd.isna(value) else str(value)
return out
@dataclass
class PredictionResult:
house_id: str
city: str
origin_time: str
target_time: str
prediction_kwh: float
interval_low_kwh: float
interval_high_kwh: float
last_hour_kwh: float
delta_kwh: float
history: list[dict] = field(default_factory=list)
def to_dict(self) -> dict:
return asdict(self)
class BijliCastService:
"""Loads the deployment bundle once and serves predictions."""
def __init__(self, root: str | Path, history_tail: int = 72) -> None:
self.root = Path(root).resolve()
self.models_dir = self.root / "models"
self.history_tail = history_tail
missing = [n for n in REQUIRED_ARTIFACTS if not (self.models_dir / n).exists()]
if missing:
raise ArtifactsMissingError(
"Missing deployment artifacts in "
f"{self.models_dir}: {', '.join(missing)}. Run "
"`python -m src.models.export_deployment` and "
"`python -m src.deploy.export_app_data` first."
)
self.model = joblib.load(self.models_dir / "deployment_model.joblib")
self.profiles = pd.read_csv(self.models_dir / "house_profiles.csv")
self.profiles[HOUSE_COL] = self.profiles[HOUSE_COL].astype(str)
self.profiles = self.profiles.sort_values(HOUSE_COL).reset_index(drop=True)
history = pd.read_parquet(self.models_dir / "usage_history.parquet")
history[HOUSE_COL] = history[HOUSE_COL].astype(str)
history[TIME_COL] = pd.to_datetime(history[TIME_COL])
self.history = history.sort_values([HOUSE_COL, TIME_COL])
latest = pd.read_csv(self.models_dir / "latest_weather.csv")
latest[HOUSE_COL] = latest[HOUSE_COL].astype(str)
latest[TIME_COL] = pd.to_datetime(latest[TIME_COL])
latest[CITY_COL] = latest[CITY_COL].astype(str)
self.latest_weather = latest.sort_values(HOUSE_COL).reset_index(drop=True)
self.metadata = json.loads(
(self.models_dir / "model_metadata.json").read_text(encoding="utf-8")
)
self.manifest = json.loads(
(self.models_dir / "app_manifest.json").read_text(encoding="utf-8")
)
self._profile_by_house = {
str(row[HOUSE_COL]): row
for _, row in self.profiles.iterrows()
}
self._latest_by_house = {
str(row[HOUSE_COL]): row
for _, row in self.latest_weather.iterrows()
}
self._history_by_house = {
str(house): g.set_index(TIME_COL)["usage_kw"].sort_index()
for house, g in self.history.groupby(HOUSE_COL, sort=False)
}
deployment = self.metadata.get("deployment_model", {})
self.model_name = str(deployment.get("name", type(self.model).__name__))
self.interval_offsets = deployment.get("prediction_interval", {})
self.deployment_metrics = deployment.get("metrics", {})
# ------------------------------------------------------------------ meta
def model_info(self) -> dict:
test = self.deployment_metrics.get("test", {})
interval = self.interval_offsets
return {
"name": self.model_name,
"n_train_rows": int(
self.metadata.get("deployment_model", {}).get(
"n_train_rows", self.metadata.get("n_train_rows", 0)
)
),
"test_mae": _finite(test.get("mae", float("nan"))),
"test_rmse": _finite(test.get("rmse", float("nan"))),
"test_r2": _finite(test.get("r2", float("nan"))),
"interval_val_coverage": _finite(
interval.get("val_coverage", float("nan"))
),
"interval_test_coverage": _finite(
interval.get("test_coverage", float("nan"))
),
"fit_data": self.metadata.get("deployment_model", {}).get("fit_data"),
}
def _house_payload(self, house_id: str) -> dict:
latest = self._latest_by_house[house_id]
profile = self._profile_by_house[house_id]
origin = pd.Timestamp(latest[TIME_COL])
return {
"house_id": house_id,
"city": str(latest[CITY_COL]),
"origin_time": origin.isoformat(),
"target_time": (origin + pd.Timedelta(hours=1)).isoformat(),
"defaults": {
key: float(latest[key]) for key in INPUT_WEATHER_FEATURES
},
"profile": _profile_payload(profile),
}
def house_ids(self) -> list[str]:
return list(self._latest_by_house)
def houses(self) -> list[dict]:
return [self._house_payload(h) for h in self.house_ids()]
def houses_response(self) -> dict:
return {"model": self.model_info(), "houses": self.houses()}
# ------------------------------------------------------------- prediction
def _weather(self, house_id: str, overrides: dict | None) -> dict:
row = self._latest_by_house[house_id]
values = {key: float(row[key]) for key in INPUT_WEATHER_FEATURES}
if overrides:
for key in INPUT_WEATHER_FEATURES:
value = overrides.get(key)
if value is None:
continue
number = float(value)
if not np.isfinite(number):
raise BijliCastError(f"weather value {key!r} is not finite")
values[key] = number
return values
def predict(
self,
house_id: str,
weather: dict | None = None,
history_tail: int | None = None,
) -> PredictionResult:
house_id = str(house_id)
if house_id not in self._latest_by_house:
raise UnknownHouseError(f"unknown household: {house_id!r}")
latest = self._latest_by_house[house_id]
profile = self._profile_by_house[house_id]
origin = pd.Timestamp(latest[TIME_COL])
city = str(latest[CITY_COL])
hist = self._history_by_house[house_id]
static = {col: profile[col] for col in STATIC_NUMERIC_FEATURES}
for col in STATIC_CATEGORICAL_FEATURES:
static[col] = profile[col]
frame = build_inference_row(
origin_time=origin,
city=city,
weather=self._weather(house_id, weather),
usage_history=hist,
static=static,
house_id=house_id,
)
raw = float(self.model.predict(frame)[0])
if not np.isfinite(raw):
raise BijliCastError("the model returned a non-finite prediction")
low_offset = float(self.interval_offsets.get("low_offset", -0.5))
high_offset = float(self.interval_offsets.get("high_offset", 0.5))
prediction = max(0.0, raw)
low = max(0.0, raw + low_offset)
high = max(low, raw + high_offset)
tail = (history_tail or self.history_tail)
recent = hist.tail(tail)
history = [
{
"time": pd.Timestamp(stamp).isoformat(),
"usage_kwh": float(value),
}
for stamp, value in recent.items()
]
return PredictionResult(
house_id=house_id,
city=city,
origin_time=origin.isoformat(),
target_time=(origin + pd.Timedelta(hours=1)).isoformat(),
prediction_kwh=prediction,
interval_low_kwh=low,
interval_high_kwh=high,
last_hour_kwh=float(hist.iloc[-1]),
delta_kwh=prediction - float(hist.iloc[-1]),
history=history,
)
@lru_cache(maxsize=4)
def get_service(root: str | Path) -> BijliCastService:
"""Process-wide cached loader (Streamlit and FastAPI each call once)."""
return BijliCastService(root)