Initial commit: astrape-oracle split out of the combined Astrape tree

The forecasting runtime gibil pilots: weather ingest (Open-Meteo forecasts and the Ecowitt station), the oracle and weather stores, the snapshot daemon, the forecast evaluator, and the TCN training scheduler. classes/datasets.py holds the shapes the stores return for display. They sit beside the stores deliberately: a store's return type belongs to the store, and keeping them with the renderers would mean this repo importing the dashboard, which is backwards. Extracted from a single repository where the forecasting engine, the database plumbing, the hardware client, the ingest daemons and the web UI all imported each other freely. Verified that every module imports with gibil resolved from its own installed checkout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-30 14:19:04 +02:00
commit ccd4e7a48c
23 changed files with 3165 additions and 0 deletions
@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from os import environ
+from sys import stderr
+from time import sleep
+
+from gibil.classes.oracle_builder import EnergyOracleBuilder
+from gibil.classes.forecast_config import EnergyForecastConfig
+from astrape_ems.classes.env import EnvLoader
+from astrape_oracle.classes.oracle_store import OracleStore
+from astrape_ems.classes.store import SigenStore
+from astrape_oracle.classes.weather.store import WeatherStore
+
+
+@dataclass(frozen=True)
+class OracleDaemonConfig:
+    poll_seconds: float
+    evaluate_forecasts: bool
+    evaluation_actual_window_minutes: float
+    evaluation_lookback_hours: float
+    evaluation_limit: int
+
+    @classmethod
+    def from_env(cls) -> "OracleDaemonConfig":
+        return cls(
+            poll_seconds=float(environ.get("ASTRAPE_ORACLE_POLL_SECONDS", "300")),
+            evaluate_forecasts=environ.get(
+                "ASTRAPE_ORACLE_EVALUATE_FORECASTS", "1"
+            ).lower()
+            not in {"0", "false", "no"},
+            evaluation_actual_window_minutes=float(
+                environ.get("ASTRAPE_ORACLE_EVALUATION_WINDOW_MINUTES", "5")
+            ),
+            evaluation_lookback_hours=float(
+                environ.get("ASTRAPE_ORACLE_EVALUATION_LOOKBACK_HOURS", "168")
+            ),
+            evaluation_limit=int(environ.get("ASTRAPE_ORACLE_EVALUATION_LIMIT", "1000")),
+        )
+
+
+class OracleDaemon:
+    """Periodically stores oracle projection curves for evaluation."""
+
+    def __init__(
+        self,
+        config: OracleDaemonConfig,
+        builder: EnergyOracleBuilder,
+        store: OracleStore,
+    ) -> None:
+        self.config = config
+        self.builder = builder
+        self.store = store
+
+    @classmethod
+    def from_env(cls) -> "OracleDaemon":
+        return cls(
+            config=OracleDaemonConfig.from_env(),
+            builder=EnergyOracleBuilder(
+                weather_history=WeatherStore.from_env(),
+                plant_history=SigenStore.from_env(),
+                config=EnergyForecastConfig.from_env(),
+            ),
+            store=OracleStore.from_env(),
+        )
+
+    def run_once(self) -> int:
+        solar_run, load_run, net_run = self.builder.build()
+        saved_count = self.store.save_runs(solar_run, load_run, net_run)
+        if self.config.evaluate_forecasts:
+            from datetime import timedelta
+
+            evaluated_count = self.store.evaluate_due_forecasts(
+                actual_window=timedelta(
+                    minutes=self.config.evaluation_actual_window_minutes
+                ),
+                lookback=timedelta(hours=self.config.evaluation_lookback_hours),
+                limit=self.config.evaluation_limit,
+            )
+            return saved_count + evaluated_count
+        return saved_count
+
+    def run_forever(self) -> None:
+        self.store.initialize()
+        while True:
+            try:
+                saved_count = self.run_once()
+                print(f"stored_oracle_records={saved_count}", flush=True)
+            except Exception as error:
+                print(f"oracle_poll_error={error}", file=stderr, flush=True)
+            sleep(self.config.poll_seconds)
+
+
+def main() -> None:
+    try:
+        EnvLoader().load()
+        args = parse_args()
+        daemon = OracleDaemon.from_env()
+        if args.once:
+            print(f"stored_oracle_records={daemon.run_once()}", flush=True)
+            return
+        daemon.run_forever()
+    except Exception as error:
+        print(f"oracle_daemon_startup_error={error}", file=stderr)
+        raise SystemExit(1) from error
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Store Astrape oracle projection curves."
+    )
+    parser.add_argument(
+        "--once",
+        action="store_true",
+        help="Save one set of oracle curves and exit.",
+    )
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from os import environ
+from sys import stderr
+from time import sleep
+
+from astrape_ems.classes.env import EnvLoader
+from astrape_oracle.classes.weather.openmeteo import (
+    OpenMeteoArchiveClient,
+    OpenMeteoClient,
+    WeatherBuilder,
+)
+from astrape_oracle.classes.weather.store import WeatherStore
+
+
+@dataclass(frozen=True)
+class DbDaemonConfig:
+    latitude: float
+    longitude: float
+    forecast_hours: int
+    truth_lookback_days: int
+    truth_end_delay_days: int
+    poll_seconds: int
+
+    @classmethod
+    def from_env(cls) -> "DbDaemonConfig":
+        return cls(
+            latitude=float(_required_env("ASTRAPE_LATITUDE")),
+            longitude=float(_required_env("ASTRAPE_LONGITUDE")),
+            forecast_hours=int(environ.get("ASTRAPE_WEATHER_FORECAST_HOURS", "48")),
+            truth_lookback_days=int(
+                environ.get("ASTRAPE_WEATHER_TRUTH_LOOKBACK_DAYS", "14")
+            ),
+            truth_end_delay_days=int(
+                environ.get("ASTRAPE_WEATHER_TRUTH_END_DELAY_DAYS", "5")
+            ),
+            poll_seconds=int(environ.get("ASTRAPE_WEATHER_POLL_SECONDS", "3600")),
+        )
+
+
+class DbDaemon:
+    """Runs builder components that populate Astrape's database."""
+
+    def __init__(
+        self,
+        config: DbDaemonConfig,
+        weather_client: OpenMeteoClient,
+        archive_client: OpenMeteoArchiveClient,
+        weather_builder: WeatherBuilder,
+        weather_store: WeatherStore,
+    ) -> None:
+        self.config = config
+        self.weather_client = weather_client
+        self.archive_client = archive_client
+        self.weather_builder = weather_builder
+        self.weather_store = weather_store
+
+    @classmethod
+    def from_env(cls) -> "DbDaemon":
+        return cls(
+            config=DbDaemonConfig.from_env(),
+            weather_client=OpenMeteoClient(),
+            archive_client=OpenMeteoArchiveClient(),
+            weather_builder=WeatherBuilder(),
+            weather_store=WeatherStore.from_env(),
+        )
+
+    def initialize(self) -> None:
+        self.weather_store.initialize()
+
+    def run_once(self) -> tuple[int, int]:
+        raw_run = self.weather_client.fetch_forecast(
+            latitude=self.config.latitude,
+            longitude=self.config.longitude,
+            forecast_hours=self.config.forecast_hours,
+        )
+        forecast_run = self.weather_builder.build_forecast_run(
+            source=raw_run.source,
+            latitude=raw_run.latitude,
+            longitude=raw_run.longitude,
+            points=raw_run.points,
+            issued_at=raw_run.issued_at,
+        )
+        forecast_count = self.weather_store.save_forecast_run(forecast_run)
+        zero_hour_truth_count = self.weather_store.save_zero_hour_forecast_as_truth(
+            forecast_run
+        )
+
+        today = datetime.now(timezone.utc).date()
+        truth_end = today - timedelta(days=self.config.truth_end_delay_days)
+        truth_start = truth_end - timedelta(days=self.config.truth_lookback_days)
+        truth_points = self.archive_client.fetch_resolved_truth(
+            latitude=self.config.latitude,
+            longitude=self.config.longitude,
+            start_date=truth_start,
+            end_date=truth_end,
+        )
+        archive_truth_count = self.weather_store.save_resolved_truth(truth_points)
+
+        return forecast_count, zero_hour_truth_count + archive_truth_count
+
+    def run_forever(self) -> None:
+        self.initialize()
+        while True:
+            forecast_count, truth_count = self.run_once()
+            print(
+                f"stored_weather_forecast_points={forecast_count} "
+                f"stored_weather_resolved_truth={truth_count}",
+                flush=True,
+            )
+            sleep(self.config.poll_seconds)
+
+
+def main() -> None:
+    try:
+        EnvLoader().load()
+        daemon = DbDaemon.from_env()
+        daemon.run_forever()
+    except Exception as error:
+        print(f"db_daemon_startup_error={error}", file=stderr)
+        raise SystemExit(1) from error
+
+
+def _required_env(name: str) -> str:
+    value = environ.get(name)
+    if not value:
+        raise RuntimeError(
+            f"{name} is required. Set ASTRAPE_DATABASE_URL, "
+            "ASTRAPE_LATITUDE, and ASTRAPE_LONGITUDE before starting db_daemon."
+        )
+    return value
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from os import environ
+from sys import stderr
+from time import sleep
+
+from astrape_ems.classes.env import EnvLoader
+from astrape_oracle.classes.weather.ecowitt import EcowittGw3000Client
+from astrape_oracle.classes.weather.store import WeatherStore
+
+
+@dataclass(frozen=True)
+class WeatherStationDaemonConfig:
+    host: str
+    poll_seconds: float
+    timeout_seconds: float
+
+    @classmethod
+    def from_env(cls) -> "WeatherStationDaemonConfig":
+        host = environ.get("ECOWITT_GW3000_HOST")
+        if not host:
+            raise RuntimeError("ECOWITT_GW3000_HOST is required")
+
+        return cls(
+            host=host,
+            poll_seconds=float(environ.get("ECOWITT_GW3000_POLL_SECONDS", "60")),
+            timeout_seconds=float(environ.get("ECOWITT_GW3000_TIMEOUT_SECONDS", "5")),
+        )
+
+
+class WeatherStationDaemon:
+    """Polls local weather station observations into TimescaleDB."""
+
+    def __init__(
+        self,
+        config: WeatherStationDaemonConfig,
+        client: EcowittGw3000Client,
+        weather_store: WeatherStore,
+    ) -> None:
+        self.config = config
+        self.client = client
+        self.weather_store = weather_store
+
+    @classmethod
+    def from_env(cls) -> "WeatherStationDaemon":
+        config = WeatherStationDaemonConfig.from_env()
+        return cls(
+            config=config,
+            client=EcowittGw3000Client(
+                host=config.host,
+                timeout_seconds=config.timeout_seconds,
+            ),
+            weather_store=WeatherStore.from_env(),
+        )
+
+    def initialize(self) -> None:
+        self.weather_store.initialize()
+
+    def run_once(self) -> int:
+        observation = self.client.fetch_observation()
+        return self.weather_store.save_station_observation(observation)
+
+    def run_forever(self) -> None:
+        self.initialize()
+        while True:
+            try:
+                saved_count = self.run_once()
+                print(
+                    f"stored_weather_station_observations={saved_count}",
+                    flush=True,
+                )
+            except Exception as error:
+                print(f"weather_station_poll_error={error}", file=stderr, flush=True)
+
+            sleep(self.config.poll_seconds)
+
+
+def main() -> None:
+    try:
+        EnvLoader().load()
+        daemon = WeatherStationDaemon.from_env()
+        args = parse_args()
+        if args.once:
+            daemon.initialize()
+            saved_count = daemon.run_once()
+            print(
+                f"stored_weather_station_observations={saved_count}",
+                flush=True,
+            )
+            return
+
+        daemon.run_forever()
+    except Exception as error:
+        print(f"weather_station_daemon_startup_error={error}", file=stderr)
+        raise SystemExit(1) from error
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Poll local Ecowitt weather station observations into Astrape."
+    )
+    parser.add_argument(
+        "--once",
+        action="store_true",
+        help="Initialize storage, save one observation, and exit.",
+    )
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    main()