HA-008 HA-009: add discovery and history pipeline

Closes #17

Closes #18

tests/api/test_entities.py

@@ -1,8 +1,11 @@
 from collections.abc import Sequence
+from datetime import datetime
 
 from fastapi.testclient import TestClient
 
 from app.ha.exceptions import HaTimeoutError
+from app.ha.discovery import DiscoveredEntity, EntityRole
+from app.ha.history import EntityHistorySeries, NumericHistoryPoint
 from app.ha.models import HaEntitySummary
 from app.ha.reader import HaReader
 from app.main import app
@@ -15,6 +18,38 @@ class FakeHaReader(HaReader):
     def read_entities(self) -> Sequence[HaEntitySummary]:
         return [HaEntitySummary(entity_id="sensor.temperature", domain="sensor")]
 
+    def discover(
+        self,
+        domains: set[str] | None = None,
+        learnable: bool | None = None,
+    ) -> Sequence[DiscoveredEntity]:
+        result = DiscoveredEntity(
+            entity_id="sensor.temperature",
+            domain="sensor",
+            device_class="temperature",
+            role=EntityRole.MEASUREMENT,
+            learnable=True,
+            reason="Numerischer Messsensor für Zeitreihen und Training.",
+        )
+        if domains and result.domain not in domains:
+            return []
+        if learnable is not None and result.learnable is not learnable:
+            return []
+        return [result]
+
+    def read_history(
+        self,
+        entity_ids: list[str],
+        start_time: datetime,
+        end_time: datetime,
+    ) -> Sequence[EntityHistorySeries]:
+        return [
+            EntityHistorySeries(
+                entity_id=entity_ids[0],
+                points=[NumericHistoryPoint(timestamp=start_time, value=21.5)],
+            )
+        ]
+
 
 class TimeoutHaReader(HaReader):
     def __init__(self) -> None:
@@ -59,3 +94,44 @@ def test_entities_maps_ha_errors_without_leaking_details() -> None:
         response = client.get("/v1/entities")
     assert response.status_code == 504
     assert response.json() == {"detail": "Home Assistant request timed out."}
+
+
+def test_discovery_filters_entities() -> None:
+    with TestClient(app) as client:
+        app.state.ha_reader = FakeHaReader()
+        response = client.get("/v1/discovery?domain=sensor&learnable=true")
+
+    assert response.status_code == 200
+    assert response.json() == [
+        {
+            "entity_id": "sensor.temperature",
+            "domain": "sensor",
+            "device_class": "temperature",
+            "state_class": None,
+            "unit_of_measurement": None,
+            "role": "measurement",
+            "learnable": True,
+            "reason": "Numerischer Messsensor für Zeitreihen und Training.",
+        }
+    ]
+
+
+def test_history_returns_normalized_series() -> None:
+    with TestClient(app) as client:
+        app.state.ha_reader = FakeHaReader()
+        response = client.get(
+            "/v1/history",
+            params=[
+                ("entity_id", "sensor.temperature"),
+                ("start_time", "2026-06-01T00:00:00Z"),
+                ("end_time", "2026-06-02T00:00:00Z"),
+            ],
+        )
+
+    assert response.status_code == 200
+    assert response.json() == [
+        {
+            "entity_id": "sensor.temperature",
+            "points": [{"timestamp": "2026-06-01T00:00:00Z", "value": 21.5}],
+        }
+    ]

tests/ha/test_discovery.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import pytest
+
+from app.ha.discovery import EntityRole, classify_entity, discover_entities
+from app.ha.models import HaEntitySummary
+
+
+@pytest.mark.parametrize(
+    ("entity", "role", "learnable"),
+    [
+        (
+            HaEntitySummary(
+                entity_id="sensor.temperature",
+                domain="sensor",
+                device_class="temperature",
+                state_class="measurement",
+                unit_of_measurement="°C",
+            ),
+            EntityRole.MEASUREMENT,
+            True,
+        ),
+        (
+            HaEntitySummary(
+                entity_id="binary_sensor.motion",
+                domain="binary_sensor",
+                device_class="motion",
+            ),
+            EntityRole.BINARY_CONTEXT,
+            True,
+        ),
+        (
+            HaEntitySummary(entity_id="person.simon", domain="person"),
+            EntityRole.CONTEXT,
+            True,
+        ),
+        (
+            HaEntitySummary(entity_id="light.living_room", domain="light"),
+            EntityRole.ACTUATOR,
+            False,
+        ),
+        (
+            HaEntitySummary(entity_id="camera.driveway", domain="camera"),
+            EntityRole.UNSUPPORTED,
+            False,
+        ),
+    ],
+)
+def test_classify_entity(
+    entity: HaEntitySummary,
+    role: EntityRole,
+    learnable: bool,
+) -> None:
+    result = classify_entity(entity)
+    assert result.role is role
+    assert result.learnable is learnable
+
+
+def test_discovery_filters_domain_and_learnable() -> None:
+    entities = [
+        HaEntitySummary(
+            entity_id="sensor.temperature",
+            domain="sensor",
+            device_class="temperature",
+        ),
+        HaEntitySummary(entity_id="sensor.status", domain="sensor"),
+        HaEntitySummary(
+            entity_id="binary_sensor.motion",
+            domain="binary_sensor",
+            device_class="motion",
+        ),
+    ]
+
+    result = discover_entities(entities, domains={" SENSOR "}, learnable=True)
+
+    assert [item.entity_id for item in result] == ["sensor.temperature"]

tests/ha/test_ha_client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from datetime import datetime, timezone
 from unittest.mock import Mock
 
 import pytest
@@ -68,4 +69,60 @@ def test_list_entities_rejects_invalid_json() -> None:
 def test_list_entities_rejects_non_list_payload() -> None:
     client = _client_with_response(_response(payload={"entity_id": "sensor.temperature"}))
     with pytest.raises(HaUnexpectedPayloadError):
-        client.list_entities()
+        client.list_entities()
+
+
+def test_get_history_calls_home_assistant_history_api() -> None:
+    response = _response(payload=[[{"entity_id": "sensor.temperature", "state": "21.0"}]])
+    client = _client_with_response(response)
+    start = datetime(2026, 6, 1, tzinfo=timezone.utc)
+    end = datetime(2026, 6, 2, tzinfo=timezone.utc)
+
+    payload = client.get_history(["sensor.temperature"], start, end)
+
+    assert payload == [[{"entity_id": "sensor.temperature", "state": "21.0"}]]
+    client._session.get.assert_called_once()  # type: ignore[attr-defined]
+    call = client._session.get.call_args  # type: ignore[attr-defined]
+    assert "/api/history/period/2026-06-01T00:00:00+00:00" in call.args[0]
+    assert call.kwargs["params"]["filter_entity_id"] == "sensor.temperature"
+    assert call.kwargs["params"]["end_time"] == "2026-06-02T00:00:00+00:00"
+
+
+@pytest.mark.parametrize(
+    ("entity_ids", "start", "end"),
+    [
+        (
+            [],
+            datetime(2026, 6, 1, tzinfo=timezone.utc),
+            datetime(2026, 6, 2, tzinfo=timezone.utc),
+        ),
+        (
+            ["sensor.temperature"],
+            datetime(2026, 6, 1),
+            datetime(2026, 6, 2, tzinfo=timezone.utc),
+        ),
+        (
+            ["sensor.temperature"],
+            datetime(2026, 6, 2, tzinfo=timezone.utc),
+            datetime(2026, 6, 1, tzinfo=timezone.utc),
+        ),
+        (
+            ["invalid entity"],
+            datetime(2026, 6, 1, tzinfo=timezone.utc),
+            datetime(2026, 6, 2, tzinfo=timezone.utc),
+        ),
+        (
+            ["sensor.temperature"],
+            datetime(2026, 5, 1, tzinfo=timezone.utc),
+            datetime(2026, 6, 2, tzinfo=timezone.utc),
+        ),
+    ],
+)
+def test_get_history_validates_request(
+    entity_ids: list[str],
+    start: datetime,
+    end: datetime,
+) -> None:
+    client = HaClient(HaClientSettings(url="http://ha.local", token="test-token"))
+    with pytest.raises(ValueError):
+        client.get_history(entity_ids, start, end)

tests/ha/test_ha_reader.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from datetime import datetime, timezone
+
 from app.ha.client import HaClient, HaClientSettings
 from app.ha.reader import HaReader
 
@@ -26,6 +28,22 @@ class FakeHaClient(HaClient):
             },
         ]
 
+    def get_history(
+        self,
+        entity_ids: list[str],
+        start_time: datetime,
+        end_time: datetime,
+    ) -> list[object]:
+        return [
+            [
+                {
+                    "entity_id": entity_ids[0],
+                    "state": "21.5",
+                    "last_changed": start_time.isoformat(),
+                }
+            ]
+        ]
+
 
 def test_ha_reader_returns_summaries() -> None:
     reader = HaReader(FakeHaClient())
@@ -35,3 +53,25 @@ def test_ha_reader_returns_summaries() -> None:
     assert domains == {"sensor", "light"}
     sensor = next(item for item in summaries if item.entity_id == "sensor.temperature")
     assert sensor.unit_of_measurement == "°C"
+
+
+def test_ha_reader_discovers_learnable_sensors() -> None:
+    reader = HaReader(FakeHaClient())
+
+    discovered = reader.discover(learnable=True)
+
+    assert [entity.entity_id for entity in discovered] == ["sensor.temperature"]
+
+
+def test_ha_reader_normalizes_history() -> None:
+    reader = HaReader(FakeHaClient())
+    start = datetime(2026, 6, 1, tzinfo=timezone.utc)
+
+    history = reader.read_history(
+        ["sensor.temperature"],
+        start,
+        datetime(2026, 6, 2, tzinfo=timezone.utc),
+    )
+
+    assert history[0].entity_id == "sensor.temperature"
+    assert history[0].points[0].value == 21.5

tests/ha/test_history.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+
+from app.ha.exceptions import HaUnexpectedPayloadError
+from app.ha.history import normalize_history_payload
+
+
+def test_normalize_history_payload_groups_and_sorts_numeric_states() -> None:
+    payload = [
+        [
+            {
+                "entity_id": "sensor.temperature",
+                "state": "22.5",
+                "last_changed": "2026-06-01T12:15:00+00:00",
+            },
+            {
+                "state": "21.0",
+                "last_changed": "2026-06-01T12:00:00Z",
+            },
+        ],
+        [
+            {
+                "entity_id": "sensor.humidity",
+                "state": 45,
+                "last_updated": "2026-06-01T12:00:00+00:00",
+            }
+        ],
+    ]
+
+    result = normalize_history_payload(payload)
+
+    assert [series.entity_id for series in result] == [
+        "sensor.humidity",
+        "sensor.temperature",
+    ]
+    temperature = result[1]
+    assert [point.value for point in temperature.points] == [21.0, 22.5]
+    assert temperature.points[0].timestamp == datetime(
+        2026, 6, 1, 12, 0, tzinfo=timezone.utc
+    )
+
+
+def test_normalize_history_payload_skips_non_numeric_and_non_finite_states() -> None:
+    payload = [
+        [
+            {
+                "entity_id": "sensor.temperature",
+                "state": state,
+                "last_changed": "2026-06-01T12:00:00+00:00",
+            }
+            for state in ("unknown", "unavailable", "nan", "inf", "-inf", True, None)
+        ]
+    ]
+
+    assert normalize_history_payload(payload) == []
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        {},
+        [{}],
+        [["invalid"]],
+        [[{"entity_id": "invalid", "state": "21", "last_changed": "2026-06-01"}]],
+        [[{"entity_id": "sensor.a", "state": "21", "last_changed": "invalid"}]],
+        [[{"state": "21", "last_changed": "2026-06-01T12:00:00+00:00"}]],
+        [
+            [
+                {
+                    "entity_id": "sensor.a",
+                    "state": "21",
+                    "last_changed": "2026-06-01T12:00:00+00:00",
+                },
+                {
+                    "entity_id": "sensor.b",
+                    "state": "22",
+                    "last_changed": "2026-06-01T12:01:00+00:00",
+                },
+            ]
+        ],
+    ],
+)
+def test_normalize_history_payload_rejects_malformed_structure(payload: object) -> None:
+    with pytest.raises(HaUnexpectedPayloadError):
+        normalize_history_payload(payload)
+
+
+def test_normalize_history_payload_accepts_empty_series() -> None:
+    assert normalize_history_payload([[]]) == []