sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/context/occupancy.py

@@ -0,0 +1,529 @@
+"""Who is in the home, and who probably caused what the sensors saw.
+
+Ambient sensing has no notion of identity. A door opening, a hallway motion
+trip, a kettle switching on -- none of these say *whose* activity they are. A
+monitoring system that assumes every event belongs to the monitored resident
+will read a daughter's Sunday visit as a sudden improvement in mobility, and a
+carer's morning round as the resident getting up early.
+
+This module estimates the household occupancy context probabilistically and
+converts it into an attribution weight per sensor:
+
+.. code-block:: text
+
+    P(resident_home | O)
+    P(visitor_present | O)
+    P(multiple_people_present | O)
+    P(event from sensor s was generated by the resident | O)
+
+The last of these is what the fusion layer consumes. The goal is explicitly
+*not* biometric identification: the platform stays compatible with
+privacy-preserving sensing, so there are no cameras, no microphones, and no
+face or voice recognition anywhere in this design. The goal is honest
+uncertainty about attribution, which is achievable from anonymous evidence:
+whether a personal device is in range, how many tracks a radar reports, and
+whether activity is happening in two places at once.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+
+import numpy as np
+from scipy.special import logsumexp
+
+from ..observations.observation import Observation, require_aware
+from ..observations.registry import SensorRegistry
+from ..observations.types import Modality
+from ..states.markov import build_generator, stationary_distribution, transition_matrix
+
+logger = logging.getLogger(__name__)
+
+EPSILON = 1e-9
+
+
+class OccupancyContext(str, Enum):
+    """Who is present in the home."""
+
+    EMPTY = "empty"
+    """Nobody present. Ambient activity here indicates a sensor problem."""
+
+    RESIDENT_ALONE = "resident_alone"
+    """Only the monitored resident. Ambient events are theirs."""
+
+    RESIDENT_WITH_VISITOR = "resident_with_visitor"
+    """Resident plus at least one other person; ambient events are shared."""
+
+    VISITOR_ONLY = "visitor_only"
+    """Someone else present while the resident is out, such as a carer."""
+
+
+#: Canonical vector order for occupancy contexts.
+CONTEXTS: tuple[OccupancyContext, ...] = (
+    OccupancyContext.EMPTY,
+    OccupancyContext.RESIDENT_ALONE,
+    OccupancyContext.RESIDENT_WITH_VISITOR,
+    OccupancyContext.VISITOR_ONLY,
+)
+
+#: Typical persistence of each context.
+DEFAULT_CONTEXT_DWELL: dict[OccupancyContext, timedelta] = {
+    OccupancyContext.EMPTY: timedelta(hours=3),
+    OccupancyContext.RESIDENT_ALONE: timedelta(hours=8),
+    OccupancyContext.RESIDENT_WITH_VISITOR: timedelta(hours=1),
+    OccupancyContext.VISITOR_ONLY: timedelta(minutes=45),
+}
+
+#: Expected share of ambient activity generated by the resident in each
+#: context. In a shared household the split is uncertain rather than known,
+#: which is precisely why attribution is a probability and not a flag.
+DEFAULT_RESIDENT_SHARE: dict[OccupancyContext, float] = {
+    OccupancyContext.EMPTY: 0.0,
+    OccupancyContext.RESIDENT_ALONE: 1.0,
+    OccupancyContext.RESIDENT_WITH_VISITOR: 0.5,
+    OccupancyContext.VISITOR_ONLY: 0.0,
+}
+
+#: Expected number of simultaneously tracked people in each context, for
+#: radar or room-occupancy devices that report a count.
+DEFAULT_TRACK_COUNTS: dict[OccupancyContext, float] = {
+    OccupancyContext.EMPTY: 0.02,
+    OccupancyContext.RESIDENT_ALONE: 1.0,
+    OccupancyContext.RESIDENT_WITH_VISITOR: 2.0,
+    OccupancyContext.VISITOR_ONLY: 1.0,
+}
+
+#: Probability a personal presence beacon reports the resident in range.
+#: Never one, because adherence is never perfect: a wearable left on the
+#: dresser is not a resident who left the house.
+DEFAULT_BEACON_PRESENCE: dict[OccupancyContext, float] = {
+    OccupancyContext.EMPTY: 0.02,
+    OccupancyContext.RESIDENT_ALONE: 0.9,
+    OccupancyContext.RESIDENT_WITH_VISITOR: 0.9,
+    OccupancyContext.VISITOR_ONLY: 0.05,
+}
+
+
+@dataclass(frozen=True)
+class ContextEstimate:
+    """The household occupancy posterior and what it implies for attribution."""
+
+    at: datetime
+    belief: np.ndarray
+    concurrency: int
+    door_events: int
+
+    def __post_init__(self) -> None:
+        """Validate and normalise the context belief."""
+        belief = np.asarray(self.belief, dtype=float)
+        if belief.shape != (len(CONTEXTS),):
+            raise ValueError("belief must have one entry per occupancy context")
+        total = belief.sum()
+        if not np.all(np.isfinite(belief)) or belief.min() < 0.0 or total <= 0.0:
+            raise ValueError("belief must be finite, non-negative, and non-zero")
+        object.__setattr__(self, "belief", belief / total)
+
+    @property
+    def probabilities(self) -> dict[OccupancyContext, float]:
+        """Posterior probability of each occupancy context."""
+        return dict(zip(CONTEXTS, (float(p) for p in self.belief)))
+
+    @property
+    def resident_home(self) -> float:
+        """``P(resident is in the home)``."""
+        return float(
+            self.belief[CONTEXTS.index(OccupancyContext.RESIDENT_ALONE)]
+            + self.belief[CONTEXTS.index(OccupancyContext.RESIDENT_WITH_VISITOR)]
+        )
+
+    @property
+    def visitor_present(self) -> float:
+        """``P(at least one other person is in the home)``."""
+        return float(
+            self.belief[CONTEXTS.index(OccupancyContext.RESIDENT_WITH_VISITOR)]
+            + self.belief[CONTEXTS.index(OccupancyContext.VISITOR_ONLY)]
+        )
+
+    @property
+    def multiple_people(self) -> float:
+        """``P(more than one person is in the home)``."""
+        return float(
+            self.belief[CONTEXTS.index(OccupancyContext.RESIDENT_WITH_VISITOR)]
+        )
+
+    @property
+    def most_likely(self) -> OccupancyContext:
+        """The highest-posterior occupancy context."""
+        return CONTEXTS[int(np.argmax(self.belief))]
+
+    def ambient_attribution(
+        self, shares: Mapping[OccupancyContext, float] | None = None
+    ) -> float:
+        """``P(an ambient event was generated by the resident)``.
+
+        Marginalises the per-context resident share over the occupancy
+        posterior. With the resident certainly alone this is one; with a
+        visitor certainly present it falls toward the shared-household split;
+        with the home empty it is zero.
+        """
+        weights = shares if shares is not None else DEFAULT_RESIDENT_SHARE
+        return float(
+            sum(
+                self.belief[index] * float(weights.get(context, 0.5))
+                for index, context in enumerate(CONTEXTS)
+            )
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a serialisable form of the estimate."""
+        return {
+            "at": self.at.isoformat(),
+            "most_likely": self.most_likely.value,
+            "resident_home": self.resident_home,
+            "visitor_present": self.visitor_present,
+            "multiple_people": self.multiple_people,
+            "ambient_attribution": self.ambient_attribution(),
+            "concurrency": self.concurrency,
+            "door_events": self.door_events,
+            "probabilities": {
+                context.value: probability
+                for context, probability in self.probabilities.items()
+            },
+        }
+
+
+@dataclass
+class ContextConfig:
+    """Configuration for occupancy context estimation.
+
+    Parameters
+    ----------
+    dwell
+        Mean persistence of each occupancy context.
+    resident_share
+        Expected share of ambient activity generated by the resident.
+    track_counts
+        Expected simultaneous track count reported by radar-style devices.
+    beacon_presence
+        Probability a personal presence beacon reports in-range.
+    door_mixing
+        How much a door event relaxes the context belief toward a transition.
+        A door crossing is the moment occupancy is most likely to change, so
+        it loosens the belief rather than supplying evidence for one context.
+    concurrency_window
+        Window used to decide that activity in two rooms was simultaneous.
+    concurrency_odds
+        Likelihood ratio favouring multi-person contexts for each additional
+        room active at once. Concurrent activity in separate rooms is the
+        strongest anonymous evidence of more than one person.
+    sample_weight
+        Discount applied to each individual presence sample. Successive
+        readings from the same radar or beacon are strongly correlated --
+        they mostly re-observe the same unchanged situation -- so counting
+        them as independent measurements would drive the posterior to
+        certainty within minutes. This is a deliberate, inspectable
+        correction rather than a claim that the samples are independent.
+    """
+
+    dwell: Mapping[OccupancyContext, timedelta] = field(
+        default_factory=lambda: dict(DEFAULT_CONTEXT_DWELL)
+    )
+    resident_share: Mapping[OccupancyContext, float] = field(
+        default_factory=lambda: dict(DEFAULT_RESIDENT_SHARE)
+    )
+    track_counts: Mapping[OccupancyContext, float] = field(
+        default_factory=lambda: dict(DEFAULT_TRACK_COUNTS)
+    )
+    beacon_presence: Mapping[OccupancyContext, float] = field(
+        default_factory=lambda: dict(DEFAULT_BEACON_PRESENCE)
+    )
+    door_mixing: float = 0.35
+    concurrency_window: timedelta = timedelta(seconds=60)
+    concurrency_odds: float = 4.0
+    sample_weight: float = 0.2
+
+    def __post_init__(self) -> None:
+        """Validate the configuration."""
+        for context in CONTEXTS:
+            duration = self.dwell.get(context)
+            if duration is None or duration <= timedelta(0):
+                raise ValueError(f"dwell for {context.value} must be positive")
+        for name in ("resident_share", "beacon_presence"):
+            values = getattr(self, name)
+            if any(not 0.0 <= float(v) <= 1.0 for v in values.values()):
+                raise ValueError(f"{name} values must lie in [0, 1]")
+        if any(float(v) < 0.0 for v in self.track_counts.values()):
+            raise ValueError("track_counts must be non-negative")
+        if not 0.0 <= self.door_mixing <= 1.0:
+            raise ValueError("door_mixing must lie in [0, 1]")
+        if self.concurrency_window <= timedelta(0):
+            raise ValueError("concurrency_window must be positive")
+        if self.concurrency_odds < 1.0:
+            raise ValueError("concurrency_odds must be at least 1")
+        if not 0.0 < self.sample_weight <= 1.0:
+            raise ValueError("sample_weight must lie in (0, 1]")
+
+
+class ResidentContextEstimator:
+    """Estimate household occupancy and per-sensor attribution online.
+
+    Parameters
+    ----------
+    registry
+        Sensor declarations. The ``attributable`` flag decides which sensors
+        identify the person behind an observation and which do not.
+    config
+        Model configuration.
+    prior
+        Initial context belief; defaults to the chain's stationary
+        distribution.
+    """
+
+    def __init__(
+        self,
+        registry: SensorRegistry,
+        config: ContextConfig | None = None,
+        prior: np.ndarray | None = None,
+    ) -> None:
+        self.registry = registry
+        self.config = config or ContextConfig()
+        rates = np.array(
+            [1.0 / self.config.dwell[context].total_seconds() for context in CONTEXTS],
+            dtype=float,
+        )
+        self._generator = build_generator(
+            rates, np.ones((len(CONTEXTS), len(CONTEXTS)))
+        )
+        self._prior: np.ndarray = (
+            stationary_distribution(self._generator)
+            if prior is None
+            else self._validated(prior)
+        )
+        self._belief: np.ndarray = self._prior.copy()
+        self._at: datetime | None = None
+
+    @staticmethod
+    def _validated(prior: np.ndarray) -> np.ndarray:
+        """Return a normalised context prior."""
+        vector = np.asarray(prior, dtype=float)
+        if vector.shape != (len(CONTEXTS),):
+            raise ValueError("prior must have one entry per occupancy context")
+        total = vector.sum()
+        if not np.all(np.isfinite(vector)) or vector.min() < 0.0 or total <= 0.0:
+            raise ValueError("prior must be finite, non-negative, and non-zero")
+        normalised: np.ndarray = vector / total
+        return normalised
+
+    # ------------------------------------------------------------------
+    @property
+    def belief(self) -> np.ndarray:
+        """A copy of the current occupancy posterior."""
+        current: np.ndarray = self._belief.copy()
+        return current
+
+    def reset(self) -> None:
+        """Return the estimator to its prior and clear its clock."""
+        self._belief = self._prior.copy()
+        self._at = None
+
+    def _per_context(
+        self, values: Mapping[OccupancyContext, float], default: float
+    ) -> np.ndarray:
+        """Expand a per-context mapping into a vector in canonical order."""
+        return np.array(
+            [float(values.get(context, default)) for context in CONTEXTS], dtype=float
+        )
+
+    def _concurrency(self, observations: Sequence[Observation]) -> int:
+        """Count distinct rooms with simultaneous activity events.
+
+        Two rooms lighting up within the concurrency window is the clearest
+        anonymous signal that more than one person is moving about: a single
+        resident cannot be in the kitchen and the bathroom at the same time.
+
+        Only discrete activation *events* count. A radar or occupancy device
+        reporting a continuous track count is not evidence of a second room
+        being used -- its count is already the stronger evidence, handled by
+        the track-count likelihood, and counting it here as well would both
+        double-count it and turn one tracked person into two.
+        """
+        located = [
+            (obs.timestamp, room)
+            for obs in observations
+            if obs.is_event
+            and obs.value != 0.0
+            and (spec := self.registry.get(obs.sensor_id)) is not None
+            and not spec.attributable
+            and (room := spec.room) is not None
+        ]
+        if len(located) < 2:
+            return len({room for _, room in located})
+
+        located.sort(key=lambda item: item[0])
+        window = self.config.concurrency_window
+        best = 1
+        for index, (start, _) in enumerate(located):
+            rooms = {
+                room for moment, room in located[index:] if moment - start <= window
+            }
+            best = max(best, len(rooms))
+        return best
+
+    def _evidence(
+        self,
+        observations: Sequence[Observation],
+        reliabilities: Mapping[str, float] | None,
+    ) -> tuple[np.ndarray, int]:
+        """Accumulate the log-likelihood of the interval over contexts."""
+        log_likelihood = np.zeros(len(CONTEXTS))
+        doors = 0
+
+        for observation in observations:
+            spec = self.registry.get(observation.sensor_id)
+            if spec is None:
+                continue
+            weight = (
+                1.0
+                if reliabilities is None
+                else float(reliabilities.get(observation.sensor_id, 1.0))
+            )
+            if weight <= 0.0:
+                continue
+
+            if spec.modality is Modality.DOOR and observation.value != 0.0:
+                doors += 1
+                continue
+
+            if spec.modality is Modality.PROXIMITY and spec.attributable:
+                presence = np.clip(
+                    self._per_context(self.config.beacon_presence, 0.5),
+                    EPSILON,
+                    1.0 - EPSILON,
+                )
+                in_range = observation.value != 0.0
+                log_likelihood += (
+                    weight
+                    * self.config.sample_weight
+                    * (np.log(presence) if in_range else np.log1p(-presence))
+                )
+                continue
+
+            if spec.modality in (Modality.RADAR, Modality.ROOM_OCCUPANCY):
+                counts = np.maximum(
+                    self._per_context(self.config.track_counts, 1.0), EPSILON
+                )
+                observed = max(observation.value, 0.0)
+                log_likelihood += (
+                    weight
+                    * self.config.sample_weight
+                    * (observed * np.log(counts) - counts)
+                )
+                continue
+
+        return log_likelihood, doors
+
+    def _concurrency_evidence(self, rooms_active: int) -> np.ndarray:
+        """Return the log-likelihood contributed by simultaneous room activity."""
+        if rooms_active < 2:
+            return np.zeros(len(CONTEXTS))
+        odds = np.log(self.config.concurrency_odds) * (rooms_active - 1)
+        multi = np.array(
+            [
+                1.0 if context is OccupancyContext.RESIDENT_WITH_VISITOR else 0.0
+                for context in CONTEXTS
+            ]
+        )
+        evidence: np.ndarray = odds * multi
+        return evidence
+
+    def update(
+        self,
+        now: datetime,
+        observations: Sequence[Observation] = (),
+        *,
+        reliabilities: Mapping[str, float] | None = None,
+    ) -> ContextEstimate:
+        """Advance the occupancy estimate to *now* over the interval's evidence."""
+        moment = require_aware(now, "now")
+        if self._at is not None and moment < self._at:
+            raise ValueError("context updates must be non-decreasing in time")
+
+        elapsed = (moment - self._at).total_seconds() if self._at is not None else 0.0
+        predicted = self._belief @ transition_matrix(self._generator, elapsed)
+
+        log_likelihood, doors = self._evidence(observations, reliabilities)
+        rooms_active = self._concurrency(observations)
+        log_likelihood = log_likelihood + self._concurrency_evidence(rooms_active)
+
+        log_belief = np.log(np.maximum(predicted, 1e-300)) + log_likelihood
+        belief = np.exp(log_belief - logsumexp(log_belief))
+
+        # A door crossing is the moment occupancy is most likely to change,
+        # so it relaxes the belief toward the transition rather than voting
+        # for any particular context. Without this the model would be far too
+        # confident that whoever was home an hour ago is still home.
+        if doors:
+            mixing = 1.0 - (1.0 - self.config.door_mixing) ** doors
+            belief = (1.0 - mixing) * belief + mixing * self._prior
+
+        self._belief = belief / belief.sum()
+        self._at = moment
+        return ContextEstimate(
+            at=moment,
+            belief=self._belief.copy(),
+            concurrency=rooms_active,
+            door_events=doors,
+        )
+
+    # ------------------------------------------------------------------
+    def attribution(self, estimate: ContextEstimate) -> dict[str, float]:
+        """Return the per-sensor attribution weights the fusion layer needs.
+
+        Sensors declared ``attributable`` -- a worn device, a personal beacon
+        -- are bound to the resident by construction and get a weight of one.
+        Every ambient sensor gets the marginal probability that the resident,
+        rather than someone else in the home, generated what it saw.
+        """
+        ambient = estimate.ambient_attribution(self.config.resident_share)
+        return {
+            spec.sensor_id: 1.0 if spec.attributable else ambient
+            for spec in self.registry
+        }
+
+    def snapshot(self) -> dict[str, object]:
+        """Return restartable estimator state."""
+        return {
+            "belief": self._belief.tolist(),
+            "at": self._at.isoformat() if self._at else None,
+            "contexts": [context.value for context in CONTEXTS],
+        }
+
+    def restore(self, state: Mapping[str, object]) -> None:
+        """Restore estimator state produced by :meth:`snapshot`."""
+        contexts = state.get("contexts")
+        if contexts is not None and list(contexts) != [c.value for c in CONTEXTS]:  # type: ignore[call-overload]
+            raise ValueError("snapshot was taken under different occupancy contexts")
+        self._belief = self._validated(np.asarray(state["belief"], dtype=float))
+        moment = state.get("at")
+        self._at = datetime.fromisoformat(str(moment)) if moment else None
+
+
+def rooms_active_at(
+    registry: SensorRegistry, observations: Iterable[Observation]
+) -> set[str]:
+    """Return the distinct rooms with ambient activations among *observations*."""
+    rooms: set[str] = set()
+    for observation in observations:
+        spec = registry.get(observation.sensor_id)
+        if (
+            spec is not None
+            and spec.room
+            and not spec.attributable
+            and observation.value
+        ):
+            rooms.add(spec.room)
+    return rooms

sensor_modeling/data/__init__.py

@@ -0,0 +1,5 @@
+"""Data loading, preprocessing, validation, and simulation utilities."""
+
+from . import loaders, preprocessing, synthetic, validation
+
+__all__ = ["loaders", "preprocessing", "validation", "synthetic"]

sensor_modeling/data/loaders.py

@@ -0,0 +1,146 @@
+"""Flexible data loaders for multiple sensor data formats."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Generator, Iterable, Mapping
+from os import PathLike
+
+import pandas as pd
+
+from sensor_modeling.utils.data_io import SensorDataset, read_sensor_csv
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_timestamps(values: object, field_name: str) -> pd.Series:
+    """Parse timestamp values and reject missing or invalid entries."""
+    timestamps = pd.to_datetime(values, errors="coerce")
+    if pd.isna(timestamps).any():
+        raise ValueError(f"Timestamp field '{field_name}' contains invalid timestamps")
+    return timestamps
+
+
+def load_csv(
+    path: str | PathLike[str], timestamp_col: str = "timestamp", **kwargs
+) -> SensorDataset:
+    """Load sensor readings from a CSV file.
+
+    Parameters
+    ----------
+    path : str
+        Path to the CSV file.
+    timestamp_col : str, default="timestamp"
+        Preferred timestamp column. If absent, an unnamed saved index is parsed
+        as datetimes when possible; otherwise the CSV is loaded as a plain
+        tabular sensor matrix.
+
+    Returns
+    -------
+    SensorDataset
+        Dataset containing sensor readings indexed by timestamps.
+    """
+    try:
+        df = read_sensor_csv(path, timestamp_col=timestamp_col, **kwargs)
+    except (
+        OSError,
+        TypeError,
+        UnicodeError,
+        ValueError,
+        pd.errors.ParserError,
+    ) as exc:
+        logger.error("Failed to read CSV %s: %s", path, exc)
+        raise ValueError(f"Unable to read CSV file: {path}") from exc
+    logger.info("Loaded CSV with shape %s from %s", df.shape, path)
+    return SensorDataset(df)
+
+
+def load_json(
+    path: str | PathLike[str], timestamp_field: str = "timestamp"
+) -> SensorDataset:
+    """Load sensor event log data from a JSON file."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            records = json.load(f)
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        logger.error("Failed to read JSON %s: %s", path, exc)
+        raise ValueError(f"Unable to read JSON file: {path}") from exc
+
+    df = _records_to_frame(records, timestamp_field=timestamp_field)
+    logger.info("Loaded JSON with shape %s from %s", df.shape, path)
+    return SensorDataset(df)
+
+
+def _records_to_frame(records: object, timestamp_field: str) -> pd.DataFrame:
+    """Convert JSON records into a timestamp-indexed DataFrame."""
+    if not isinstance(records, list):
+        raise ValueError("JSON file must contain a list of records")
+    if any(not isinstance(record, Mapping) for record in records):
+        raise ValueError("Invalid JSON structure for tabular data")
+
+    try:
+        df = pd.DataFrame(records)
+    except (TypeError, ValueError) as exc:
+        logger.error("JSON structure invalid: %s", exc)
+        raise ValueError("Invalid JSON structure for tabular data") from exc
+
+    if timestamp_field not in df.columns:
+        raise ValueError(
+            f"Timestamp field '{timestamp_field}' missing from JSON records"
+        )
+
+    df[timestamp_field] = _parse_timestamps(df[timestamp_field], timestamp_field)
+    return df.set_index(timestamp_field).sort_index()
+
+
+def load_hdf5(path: str | PathLike[str], key: str = "data") -> SensorDataset:
+    """Load sensor data from an HDF5 file."""
+    try:
+        import h5py
+    except ImportError as exc:  # pragma: no cover - dependency is installed in CI
+        raise ImportError("h5py is required for HDF5 support") from exc
+
+    try:
+        with h5py.File(path, "r") as h5:
+            if key not in h5:
+                raise ValueError(f"Dataset '{key}' not found in HDF5 file")
+            data = pd.DataFrame(h5[key][:])
+            if "timestamp" in h5[key].attrs:
+                ts = pd.to_datetime(h5[key].attrs["timestamp"])
+                data.index = ts
+    except OSError as exc:
+        logger.error("Failed to read HDF5 %s: %s", path, exc)
+        raise ValueError(f"Unable to read HDF5 file: {path}") from exc
+    logger.info("Loaded HDF5 dataset '%s' with shape %s from %s", key, data.shape, path)
+    return SensorDataset(data)
+
+
+def stream_data(source: Iterable[object]) -> Generator[SensorDataset, None, None]:
+    """Yield datasets from a real-time streaming source.
+
+    Parameters
+    ----------
+    source : Iterable[Dict]
+        Iterable producing dictionaries with sensor readings and timestamps.
+    """
+    for item in source:
+        try:
+            yield _stream_item_to_dataset(item)
+        except (TypeError, ValueError, KeyError) as exc:
+            logger.warning("Skipping malformed streaming item %s: %s", item, exc)
+            continue
+
+
+def _stream_item_to_dataset(item: object) -> SensorDataset:
+    """Convert one streaming record into a single-row dataset."""
+    if not isinstance(item, Mapping):
+        raise TypeError("Streaming item must be a mapping")
+
+    timestamp = item.get("timestamp")
+    if timestamp is None:
+        raise ValueError("Streaming item missing 'timestamp' field")
+
+    timestamp_index = _parse_timestamps([timestamp], "timestamp")
+    df = pd.DataFrame([item]).set_index(timestamp_index)
+    return SensorDataset(df.drop(columns=["timestamp"]))