ogre-sdk 0.1.0__py3-none-any.whl

ogre_sdk/__init__.py

@@ -0,0 +1,75 @@
+"""Ogre SDK — Python client for the Ogre forecasting APIs.
+
+Example::
+
+    from ogre_sdk import Ogre
+    from datetime import datetime
+
+    client = Ogre(api_key="<your-key>")
+
+    consumer = client.consumers.create(
+        "My Site", 53.35, -6.26,
+        project_id="...", dso_id="...", profile_id="...", external_id="...",
+    )
+    client.meteo_locations.ingest_historical(consumer.meteo_location,
+        start_date=datetime(2016, 1, 1), end_date=datetime(2017, 12, 31))
+    client.training.run(consumer, consumer.forecast_settings, project_id="...",
+        start_date=datetime(2016, 1, 1), end_date=datetime(2017, 12, 31))
+    client.forecasts.run(consumer, consumer.forecast_settings, project_id="...",
+        start_date=datetime(2018, 1, 1), end_date=datetime(2018, 2, 1))
+    result = client.forecasts.get(consumer, consumer.forecast_settings, project_id="...",
+        start_date=datetime(2018, 1, 1), end_date=datetime(2018, 2, 1))
+"""
+
+from ._resource import PendingJob
+from .client import Ogre
+from .exceptions import OgreAPIError, OgreError
+from .models import (
+    Consumer,
+    Dso,
+    ForecastResult,
+    ForecastSettings,
+    IngestionSetting,
+    MeteoLocation,
+    MeteoSource,
+    Page,
+    Profile,
+    TrainedModel,
+)
+from .resources import (
+    Consumers,
+    Forecasts,
+    IngestionSettings,
+    MeteoLocations,
+    MeteoSources,
+    Training,
+)
+from .resources import (
+    ForecastSettings as ForecastSettingsResource,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Consumer",
+    "Consumers",
+    "Dso",
+    "ForecastResult",
+    "ForecastSettings",
+    "ForecastSettingsResource",
+    "Forecasts",
+    "IngestionSetting",
+    "IngestionSettings",
+    "MeteoLocation",
+    "MeteoLocations",
+    "MeteoSource",
+    "MeteoSources",
+    "Ogre",
+    "OgreAPIError",
+    "OgreError",
+    "Page",
+    "PendingJob",
+    "Profile",
+    "TrainedModel",
+    "Training",
+]

ogre_sdk/_http.py

@@ -0,0 +1,44 @@
+"""Internal HTTP session wrapper for authenticated API requests."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from .exceptions import OgreAPIError
+
+
+class _Session:
+    def __init__(self, api_key: str, base_url: str, timeout: int = 30) -> None:
+        self._session = requests.Session()
+        if api_key:
+            self._session.headers.update({"ApiKey": api_key})
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    @staticmethod
+    def _raise_for_status(response: requests.Response) -> None:
+        if not response.ok:
+            try:
+                detail = response.json().get("detail", response.reason)
+            except ValueError:
+                detail = response.reason
+            raise OgreAPIError(
+                status_code=response.status_code,
+                message=detail,
+                response_body=response.text,
+            )
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        r = self._session.get(self._url(path), timeout=self.timeout, **kwargs)
+        _Session._raise_for_status(r)
+        return r.json()
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        r = self._session.post(self._url(path), timeout=self.timeout, **kwargs)
+        _Session._raise_for_status(r)
+        return r.json()

ogre_sdk/_resource.py

@@ -0,0 +1,83 @@
+"""Base class shared by all resource clients."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from ._http import _Session
+
+
+class PendingJob[T]:
+    """A submitted async API operation; call .wait() to block until it completes."""
+
+    def __init__(
+        self,
+        raw: dict[str, Any],
+        *,
+        wait_fn: Callable[[int, int], T],
+        poll_interval: int = 20,
+        timeout: int = 600,
+    ) -> None:
+        self._raw = raw
+        self._wait_fn = wait_fn
+        self._poll_interval = poll_interval
+        self._timeout = timeout
+
+    def wait(self, *, poll_interval: int | None = None, timeout: int | None = None) -> T:
+        """Block until the operation completes."""
+        return self._wait_fn(
+            poll_interval if poll_interval is not None else self._poll_interval,
+            timeout if timeout is not None else self._timeout,
+        )
+
+    def __getitem__(self, key: str) -> Any:
+        return self._raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._raw.get(key, default)
+
+    def __repr__(self) -> str:
+        return f"PendingJob({self._raw!r})"
+
+
+class _BaseResource:
+    def __init__(self, http: _Session, *, project_id: str | None = None) -> None:
+        self._http = http
+        self._project_id = project_id
+        self._log = logging.getLogger(f"ogre.{type(self).__name__.lower()}")
+
+    def _resolve_project_id(self, project_id: str | None) -> str:
+        resolved = project_id or self._project_id
+        if not resolved:
+            msg = "project_id must be provided either at the client level (Ogre(project_id=...)) or per-call."
+            raise ValueError(msg)
+        return resolved
+
+    def _sleep(self, seconds: int, reason: str) -> None:
+        if seconds > 0:
+            self._log.info("Waiting %ds for %s...", seconds, reason)
+            time.sleep(seconds)
+
+    def _poll(
+        self,
+        check: Callable[[], Any],
+        *,
+        poll_interval: int,
+        timeout: int,
+        description: str,
+    ) -> Any:
+        deadline = time.monotonic() + timeout
+        while True:
+            result = check()
+            if result:
+                self._log.info("%s complete", description)
+                return result
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                msg = f"{description} not available after {timeout}s"
+                raise TimeoutError(msg)
+            self._log.info("Not ready yet, retrying in %ds (%s)...", poll_interval, description)
+            time.sleep(min(poll_interval, remaining))

ogre_sdk/client.py

@@ -0,0 +1,72 @@
+"""Top-level Ogre client for accessing all Ogre API resources."""
+
+from __future__ import annotations
+
+from ._http import _Session
+from .resources import (
+    Consumers,
+    Forecasts,
+    ForecastSettings,
+    IngestionSettings,
+    MeteoLocations,
+    MeteoSources,
+    Training,
+)
+
+
+class Ogre:
+    """Python client for the Ogre forecasting APIs.
+
+    Example::
+
+        client = Ogre(api_key="<your-key>", project_id="<your-project-id>")
+        # Optional overrides: demand_url=..., project_id can also be passed per-call
+
+        consumer = client.consumers.create(
+            "My Site", 53.35, -6.26,
+            dso_id="...", profile_id="...", external_id="...",
+        )
+        client.meteo_locations.ingest_historical(location, start_date=..., end_date=...)
+        client.training.run(consumer, fs, start_date=..., end_date=...)
+        client.forecasts.run(consumer, fs, start_date=..., end_date=...)
+        result = client.forecasts.get(consumer, fs, start_date=..., end_date=...)
+    """
+
+    DEFAULT_DEMAND_URL = "https://api.dev.ogre.ai/demand"
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        demand_url: str = DEFAULT_DEMAND_URL,
+        project_id: str | None = None,
+        http_timeout: int = 30,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            api_key: Your Ogre API key.
+            demand_url: Base URL for the demand service. Defaults to the production endpoint.
+            project_id: Default project ID used for all demand requests. Can be overridden
+                per-call by passing ``project_id=`` to individual methods.
+            http_timeout: Request timeout in seconds.
+
+        """
+        demand_http = _Session(api_key, demand_url, timeout=http_timeout)
+
+        self.meteo_sources = MeteoSources(demand_http)
+        self.meteo_locations = MeteoLocations(demand_http, project_id=project_id)
+        self.ingestion_settings = IngestionSettings(demand_http, self.meteo_sources)
+        self.forecast_settings = ForecastSettings(demand_http, project_id=project_id)
+        self.training = Training(demand_http, project_id=project_id)
+        self.forecasts = Forecasts(demand_http, project_id=project_id)
+        self.consumers = Consumers(
+            demand_http,
+            project_id=project_id,
+            meteo_locations=self.meteo_locations,
+            ingestion_settings=self.ingestion_settings,
+            meteo_sources=self.meteo_sources,
+            forecast_settings=self.forecast_settings,
+            training=self.training,
+            forecasts=self.forecasts,
+        )

ogre_sdk/exceptions.py

@@ -0,0 +1,16 @@
+"""Exception types raised by the Ogre SDK."""
+
+
+class OgreError(Exception):
+    """Base class for all Ogre SDK errors."""
+
+
+class OgreAPIError(OgreError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, message: str, response_body: str) -> None:
+        """Initialize with the HTTP status code, error message, and raw response body."""
+        self.status_code = status_code
+        self.message = message
+        self.response_body = response_body
+        super().__init__(f"HTTP {status_code}: {message}")

ogre_sdk/models.py

@@ -0,0 +1,192 @@
+"""Pydantic model definitions for Ogre API response objects."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, PrivateAttr
+
+
+class MeteoLocation(BaseModel):
+    """A geographic location used for meteorological data ingestion."""
+
+    id: str
+    name: str
+    latitude: float
+    longitude: float
+    meteo_type: str
+
+
+class MeteoSource(BaseModel):
+    """An external meteorological data provider."""
+
+    id: str
+    name: str
+
+
+class IngestionSetting(BaseModel):
+    """Configuration for ingesting data from a meteo source into a location."""
+
+    id: str
+    enabled: bool
+    meteo_source_id: str
+    params: list[dict[str, Any]]
+
+
+class Dso(BaseModel):
+    """A distribution system operator."""
+
+    id: str
+    name: str
+
+
+class Profile(BaseModel):
+    """A load profile attached to a consumer."""
+
+    id: str
+    name: str
+    description: str | None = None
+    external_id: str | None = None
+    dso_id: str | None = None
+    date_added: str | None = None
+    last_updated: str | None = None
+    project_id: str | None = None
+    total_consumers: int | None = None
+
+
+class Consumer(BaseModel):
+    """An electricity demand consumer (e.g. a site or meter)."""
+
+    id: str
+    name: str
+    external_id: str
+    latitude: float | None = None
+    longitude: float | None = None
+    has_realtime_data: bool
+    dso: Dso
+    profile: Profile | None = None
+    location: str | None = None
+    country: str | None = None
+    location_type: str | None = None
+    industry: str | None = None
+    voltage_type: str | None = None
+    type: str | None = None
+    expiry_date: str | None = None
+    date_added: str | None = None
+    consumer_forecast: float | None = None
+    meta: dict[str, Any] | None = None
+    profile_name: str | None = None
+    cluster_ids: list[str] | None = None
+    created_at: str
+    updated_at: str
+    first_historical_timestamp: str | None = None
+    last_historical_timestamp: str | None = None
+    meteo_location: MeteoLocation | None = None
+    forecast_settings: ForecastSettings | None = None
+
+    _meteo_locations: Any = PrivateAttr(default=None)
+    _consumers_resource: Any = PrivateAttr(default=None)
+    _training: Any = PrivateAttr(default=None)
+    _forecasts: Any = PrivateAttr(default=None)
+
+    def _require_bound(self, name: str) -> None:
+        if self._consumers_resource is None:
+            raise RuntimeError(
+                f"Consumer.{name}() requires the consumer to be fetched via the client "
+                "(client.consumers.create() or client.consumers.get())."
+            )
+
+    def ingest_meteo(self, start_date: datetime, end_date: datetime, *, time_resolution: int = 15) -> Any:
+        """Trigger historical meteo data ingestion for this consumer's location."""
+        self._require_bound("ingest_meteo")
+        if self.meteo_location is None:
+            raise RuntimeError("Consumer has no meteo_location attached.")
+        return self._meteo_locations.ingest_historical(
+            self.meteo_location, start_date, end_date, time_resolution=time_resolution
+        )
+
+    def import_historical(
+        self,
+        csv_path: str | Path,
+        *,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Upload a historical consumption CSV for this consumer."""
+        self._require_bound("import_historical")
+        return self._consumers_resource.import_historical(
+            csv_path,
+            consumer_id=self.id,
+            start_date=start_date,
+            end_date=end_date,
+            **kwargs,
+        )
+
+    def get_historical(self, start_date: datetime, end_date: datetime) -> list[dict[str, Any]]:
+        """Return historical consumption data points for this consumer."""
+        self._require_bound("get_historical")
+        return self._consumers_resource.get_historical(self.id, start_date, end_date)
+
+    def train(self, start_date: datetime, end_date: datetime) -> Any:
+        """Submit a training job for this consumer."""
+        self._require_bound("train")
+        if self.forecast_settings is None:
+            raise RuntimeError("Consumer has no forecast_settings attached.")
+        return self._training.run(self, self.forecast_settings, start_date, end_date)
+
+    def run_forecast(self, start_date: datetime, end_date: datetime) -> Any:
+        """Submit a forecast run for this consumer."""
+        self._require_bound("run_forecast")
+        if self.forecast_settings is None:
+            raise RuntimeError("Consumer has no forecast_settings attached.")
+        return self._forecasts.run(self, self.forecast_settings, start_date, end_date)
+
+    def get_forecast(self, start_date: datetime, end_date: datetime) -> Any:
+        """Download forecast results for this consumer."""
+        self._require_bound("get_forecast")
+        if self.forecast_settings is None:
+            raise RuntimeError("Consumer has no forecast_settings attached.")
+        return self._forecasts.get(self, self.forecast_settings, start_date, end_date)
+
+
+class ForecastSettings(BaseModel):
+    """Forecast configuration attached to a consumer."""
+
+    id: str
+    name: str
+    time_resolution: int
+    enabled: bool
+    meteo_sources: list[str]
+    meteo_locations_ingestion_settings: list[str]
+
+
+class ForecastResult(BaseModel):
+    """Forecast output returned by the API."""
+
+    data: list[dict[str, Any]]
+
+
+class TrainedModel(BaseModel):
+    """A trained demand forecast model."""
+
+    id: str
+    revision_meta: dict[str, Any]
+    bucket_path: str
+    created_at: str
+    training_timestamp: str | None
+    requested_interval: list[Any] | None
+    available_interval: list[Any] | None
+    kpis: dict[str, Any] | None
+
+
+class Page(BaseModel):
+    """A paginated API response."""
+
+    items: list[Any]
+    total: int
+    page: int
+    size: int
+    pages: int

ogre_sdk/resources/__init__.py

@@ -0,0 +1,19 @@
+"""Resource classes exposing each section of the Ogre API."""
+
+from .consumers import Consumers
+from .forecast_settings import ForecastSettings
+from .forecasts import Forecasts
+from .ingestion_settings import IngestionSettings
+from .meteo_locations import MeteoLocations
+from .meteo_sources import MeteoSources
+from .training import Training
+
+__all__ = [
+    "Consumers",
+    "ForecastSettings",
+    "Forecasts",
+    "IngestionSettings",
+    "MeteoLocations",
+    "MeteoSources",
+    "Training",
+]

ogre_sdk/resources/consumers.py

@@ -0,0 +1,226 @@
+"""Resource client for electricity demand consumers."""
+
+from __future__ import annotations
+
+import io
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from .._http import _Session
+from .._resource import PendingJob, _BaseResource
+from ..exceptions import OgreError
+from ..models import Consumer, MeteoLocation, MeteoSource, Page
+from .forecast_settings import ForecastSettings as ForecastSettingsResource
+from .forecasts import Forecasts
+from .ingestion_settings import IngestionSettings
+from .meteo_locations import MeteoLocations
+from .meteo_sources import MeteoSources
+from .training import Training
+
+
+class Consumers(_BaseResource):
+    """Manage electricity demand consumers."""
+
+    def __init__(
+        self,
+        http: _Session,
+        *,
+        project_id: str | None = None,
+        meteo_locations: MeteoLocations,
+        ingestion_settings: IngestionSettings,
+        meteo_sources: MeteoSources,
+        forecast_settings: ForecastSettingsResource,
+        training: Training,
+        forecasts: Forecasts,
+    ) -> None:
+        """Initialize the resource with an authenticated HTTP session."""
+        super().__init__(http, project_id=project_id)
+        self._meteo_locations = meteo_locations
+        self._ingestion_settings = ingestion_settings
+        self._meteo_sources = meteo_sources
+        self._forecast_settings = forecast_settings
+        self._training = training
+        self._forecasts = forecasts
+
+    def list(
+        self,
+        *,
+        project_id: str | None = None,
+        search: str | None = None,
+        page: int = 1,
+        size: int = 50,
+    ) -> Page:
+        """Return a paginated list of consumers for a project."""
+        pid = self._resolve_project_id(project_id)
+        params: dict[str, Any] = {"page": page, "size": size}
+        if search is not None:
+            params["search"] = search
+        return Page.model_validate(self._http.get(f"/electricity/demand/{pid}/consumers", params=params))
+
+    def _bind(self, consumer: Consumer) -> Consumer:
+        consumer._meteo_locations = self._meteo_locations
+        consumer._consumers_resource = self
+        consumer._training = self._training
+        consumer._forecasts = self._forecasts
+        return consumer
+
+    def get(self, consumer_id: str, *, project_id: str | None = None) -> Consumer:
+        """Return a single consumer by ID, with meteo_location and forecast_settings populated."""
+        pid = self._resolve_project_id(project_id)
+        consumer = Consumer.model_validate(self._http.get(f"/electricity/demand/{pid}/consumers/{consumer_id}"))
+        if consumer.latitude is not None and consumer.longitude is not None:
+            consumer.meteo_location = self._find_location_by_coords(consumer.latitude, consumer.longitude)
+        settings = self._forecast_settings.list(consumer, project_id=pid)
+        consumer.forecast_settings = settings[0] if settings else None
+        return self._bind(consumer)
+
+    def get_historical(
+        self,
+        consumer_id: str,
+        start_date: datetime,
+        end_date: datetime,
+        *,
+        project_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Return historical consumption data points for a consumer."""
+        pid = self._resolve_project_id(project_id)
+        return self._http.get(
+            f"/electricity/demand/{pid}/consumers/{consumer_id}/historical",
+            params={
+                "from_datetime": start_date.isoformat(),
+                "to_datetime": end_date.isoformat(),
+            },
+        )
+
+    def create(
+        self,
+        name: str,
+        latitude: float,
+        longitude: float,
+        dso_id: str,
+        profile_id: str,
+        *,
+        project_id: str | None = None,
+        external_id: str,
+        has_realtime_data: bool = False,
+        meteo_sources: list[MeteoSource] | None = None,
+        existing_location: bool = True,
+        forecast_resolution: int = 15,
+    ) -> Consumer:
+        """Create a consumer with auto-provisioned meteo location, ingestion settings, and forecast settings.
+
+        When *existing_location* is True the method searches for a meteo location
+        that already has the same coordinates; if one is found it is reused.  Either
+        way, fresh ingestion settings are always created.  If no match is found, or
+        when the flag is False, a new meteo location is created as well.
+
+        Note: when a location is reused, calling ``ingest_historical`` on it will
+        run ingestion for *all* enabled ingestion settings on that location, not only
+        the ones created here.  This may ingest more meteo data than strictly
+        necessary, but it does not affect forecast accuracy — the forecast settings
+        returned here reference only the newly created ingestion settings.
+        """
+        pid = self._resolve_project_id(project_id)
+        if existing_id := self._find_by_external_id(external_id, pid):
+            raise OgreError(f"A consumer with external_id {external_id!r} already exists (id={existing_id}).")
+        payload = {
+            "name": name,
+            "external_id": external_id,
+            "latitude": latitude,
+            "longitude": longitude,
+            "has_realtime_data": has_realtime_data,
+            "dso_id": dso_id,
+            "profile_id": profile_id,
+        }
+        consumer = Consumer.model_validate(self._http.post(f"/electricity/demand/{pid}/consumers", json=payload))
+        self._log.info("Created consumer %r (id=%s)", consumer.name, consumer.id)
+
+        sources = meteo_sources if meteo_sources is not None else self._meteo_sources.list()
+
+        if existing_location:
+            location = self._find_location_by_coords(latitude, longitude)
+            if location is not None:
+                self._log.info("Reusing existing meteo location (id=%s)", location.id)
+            else:
+                location = self._meteo_locations.create(consumer, project_id=pid)
+        else:
+            location = self._meteo_locations.create(consumer, project_id=pid)
+
+        ingest_settings = self._ingestion_settings.create(location, sources)
+
+        forecast_settings = self._forecast_settings.create(
+            consumer, ingest_settings, sources, project_id=pid, time_resolution=forecast_resolution
+        )
+
+        consumer.meteo_location = location
+        consumer.forecast_settings = forecast_settings
+        return self._bind(consumer)
+
+    def _find_by_external_id(self, external_id: str, project_id: str) -> str | None:
+        """Return the id of the consumer whose external_id is an exact match, or None."""
+        page = 1
+        while True:
+            result = self.list(search=external_id, project_id=project_id, page=page, size=50)
+            for item in result.items:
+                if item["external_id"] == external_id:
+                    return item["id"]
+            if page >= result.pages:
+                break
+            page += 1
+        return None
+
+    def _find_location_by_coords(self, latitude: float, longitude: float) -> MeteoLocation | None:
+        """Return the first meteo location matching the given coordinates, or None."""
+        page = 1
+        while True:
+            result = self._meteo_locations.list(page=page, size=50)
+            for loc in result.items:
+                if loc["latitude"] == latitude and loc["longitude"] == longitude:
+                    return MeteoLocation.model_validate(loc)
+            if page >= result.pages:
+                break
+            page += 1
+        return None
+
+    def import_historical(
+        self,
+        csv_path: str | Path,
+        *,
+        project_id: str | None = None,
+        consumer_id: str | None = None,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+        pattern: str = "DEFAULT_HISTORICAL_OGRE_1",
+        timestamp_column: str = "Timestamp",
+        anomaly_detection_enabled: bool = False,
+        service: str = "S3",
+    ) -> PendingJob[None]:
+        """Upload historical consumption CSV; call .wait() on the result to poll for completion."""
+        pid = self._resolve_project_id(project_id)
+        csv_path = Path(csv_path)
+        files = {"file": (csv_path.name, io.BytesIO(csv_path.read_bytes()), "text/csv")}
+        params = {
+            "pattern": pattern,
+            "columns": json.dumps({"timestamp": timestamp_column}),
+            "anomaly_detection_enabled": str(anomaly_detection_enabled).lower(),
+            "service": service,
+        }
+        result = self._http.post(
+            f"/electricity/demand/{pid}/consumers/historical",
+            params=params,
+            files=files,
+        )
+        self._log.info("Historical import submitted (job_id=%s)", result.get("import_job_id"))
+
+        def _wait(poll_interval: int, timeout: int) -> None:
+            if consumer_id is not None and start_date is not None and end_date is not None:
+                self._poll(
+                    lambda: self.get_historical(consumer_id, start_date, end_date, project_id=pid),
+                    poll_interval=poll_interval,
+                    timeout=timeout,
+                    description="historical import",
+                )
+
+        return PendingJob(result, wait_fn=_wait, poll_interval=20, timeout=300)

ogre_sdk/resources/forecast_settings.py

@@ -0,0 +1,64 @@
+"""Resource client for forecast configuration."""
+
+from __future__ import annotations
+
+from .._http import _Session
+from .._resource import _BaseResource
+from ..models import Consumer, IngestionSetting, MeteoSource
+from ..models import ForecastSettings as ForecastSettingsModel
+
+
+class ForecastSettings(_BaseResource):
+    """Manage forecast configurations for consumers."""
+
+    def __init__(self, http: _Session, *, project_id: str | None = None) -> None:
+        """Initialize the resource with an authenticated HTTP session."""
+        super().__init__(http, project_id=project_id)
+
+    def list(self, consumer: Consumer, *, project_id: str | None = None) -> list[ForecastSettingsModel]:
+        """Return all forecast settings for a consumer."""
+        pid = self._resolve_project_id(project_id)
+        return [
+            ForecastSettingsModel.model_validate(s)
+            for s in self._http.get(f"/electricity/demand/{pid}/consumers/{consumer.id}/forecast-settings")
+        ]
+
+    def get(
+        self, consumer: Consumer, forecast_settings_id: str, *, project_id: str | None = None
+    ) -> ForecastSettingsModel:
+        """Return a single forecast settings object by ID."""
+        pid = self._resolve_project_id(project_id)
+        return ForecastSettingsModel.model_validate(
+            self._http.get(
+                f"/electricity/demand/{pid}/consumers/{consumer.id}/forecast-settings/{forecast_settings_id}"
+            )
+        )
+
+    def create(
+        self,
+        consumer: Consumer,
+        ingestion_settings: list[IngestionSetting],
+        meteo_sources: list[MeteoSource],
+        *,
+        project_id: str | None = None,
+        name: str = "Forecast 15min",
+        time_resolution: int = 15,
+        use_realtime_data: bool = False,
+        horizon: int | None = None,
+    ) -> ForecastSettingsModel:
+        """Attach forecast configuration to a consumer."""
+        payload = {
+            "name": name,
+            "time_resolution": time_resolution,
+            "use_realtime_data": use_realtime_data,
+            "enabled": True,
+            "meteo_sources": [ms.id for ms in meteo_sources],
+            "use_external_meteo_data": False,
+            "horizon": horizon,
+            "meteo_locations_ingestion_settings": [str(s.id) for s in ingestion_settings],
+        }
+        pid = self._resolve_project_id(project_id)
+        path = f"/electricity/demand/{pid}/consumers/{consumer.id}/forecast-settings"
+        result = ForecastSettingsModel.model_validate(self._http.post(path, json=payload))
+        self._log.info("Created forecast settings %r (id=%s)", result.name, result.id)
+        return result

ogre_sdk/resources/forecasts.py

@@ -0,0 +1,75 @@
+"""Resource client for running and retrieving demand forecasts."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .._http import _Session
+from .._resource import PendingJob, _BaseResource
+from ..models import Consumer, ForecastResult, ForecastSettings
+
+
+class Forecasts(_BaseResource):
+    """Trigger and retrieve demand forecast runs."""
+
+    def __init__(self, http: _Session, *, project_id: str | None = None) -> None:
+        """Initialize the resource with an authenticated HTTP session."""
+        super().__init__(http, project_id=project_id)
+
+    def run(
+        self,
+        consumer: Consumer,
+        forecast_settings: ForecastSettings,
+        start_date: datetime,
+        end_date: datetime,
+        *,
+        project_id: str | None = None,
+        triggered_by: str = "external",
+    ) -> PendingJob[ForecastResult]:
+        """Submit a forecast run; call .wait() on the result to block until data is ready."""
+        pid = self._resolve_project_id(project_id)
+        payload: dict[str, Any] = {
+            "start_date": start_date.isoformat(),
+            "end_date": end_date.isoformat(),
+            "triggered_by": triggered_by,
+        }
+        path = (
+            f"/electricity/demand/{pid}/consumers/{consumer.id}/forecast-settings/{forecast_settings.id}/run-forecast"
+        )
+        result = self._http.post(path, json=payload)
+        self._log.info("Forecast run submitted: %s", result)
+
+        def _wait(poll_interval: int, timeout: int) -> ForecastResult:
+            return self._poll(
+                lambda: self.get(consumer, forecast_settings, start_date, end_date, project_id=pid),
+                poll_interval=poll_interval,
+                timeout=timeout,
+                description="forecast",
+            )
+
+        return PendingJob(result, wait_fn=_wait, poll_interval=20, timeout=600)
+
+    def get(
+        self,
+        consumer: Consumer,
+        forecast_settings: ForecastSettings,
+        start_date: datetime,
+        end_date: datetime,
+        *,
+        project_id: str | None = None,
+    ) -> ForecastResult:
+        """Download forecast results for a given period."""
+        pid = self._resolve_project_id(project_id)
+        path = f"/electricity/demand/{pid}/consumers/{consumer.id}/forecast-settings/{forecast_settings.id}/forecast"
+        result = self._http.get(
+            path,
+            params={
+                "from_datetime": start_date.isoformat(),
+                "to_datetime": end_date.isoformat(),
+            },
+        )
+        count = len(result)
+        if count:
+            self._log.info("Forecast downloaded (%d records)", count)
+        return result

ogre_sdk/resources/ingestion_settings.py

@@ -0,0 +1,55 @@
+"""Resource client for meteo data ingestion settings."""
+
+from __future__ import annotations
+
+from .._http import _Session
+from .._resource import _BaseResource
+from ..models import IngestionSetting, MeteoLocation, MeteoSource
+from .meteo_sources import MeteoSources
+
+
+class IngestionSettings(_BaseResource):
+    """Configure meteo source ingestion for locations."""
+
+    def __init__(self, http: _Session, meteo_sources: MeteoSources) -> None:
+        """Initialize the resource with an HTTP session and a MeteoSources client."""
+        super().__init__(http)
+        self._meteo_sources = meteo_sources
+
+    def list(self, location: MeteoLocation) -> list[IngestionSetting]:
+        """Return all ingestion settings for a meteo location."""
+        return [
+            IngestionSetting.model_validate(s)
+            for s in self._http.get(f"/meteo/locations/{location.id}/ingestion-settings")
+        ]
+
+    def create(
+        self,
+        location: MeteoLocation,
+        meteo_sources: list[MeteoSource] | None = None,
+        *,
+        preset: str = "demand_electricity",
+    ) -> list[IngestionSetting]:
+        """Configure which meteo sources feed data into a location."""
+        sources = meteo_sources if meteo_sources is not None else self._meteo_sources.list()
+        if preset == "demand_electricity":
+            sources = [s for s in sources if s.name == "meteomatics-ecmwf-ifs"]
+        settings: list[IngestionSetting] = []
+        for source in sources:
+            params = self._http.get(
+                f"/meteo/sources/{source.id}/params",
+                params={"preset": preset},
+            )
+            result = IngestionSetting.model_validate(
+                self._http.post(
+                    f"/meteo/locations/{location.id}/ingestion-settings",
+                    json={"enabled": True, "params": params, "meteo_source_id": source.id},
+                )
+            )
+            settings.append(result)
+            self._log.info(
+                "Created ingestion setting for source %r (id=%s)",
+                source.name,
+                result.id,
+            )
+        return settings

ogre_sdk/resources/meteo_locations.py

@@ -0,0 +1,81 @@
+"""Resource client for meteorological locations."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .._http import _Session
+from .._resource import PendingJob, _BaseResource
+from ..models import Consumer, MeteoLocation, Page
+
+
+class MeteoLocations(_BaseResource):
+    """Manage meteorological locations."""
+
+    def __init__(self, http: _Session, *, project_id: str | None = None) -> None:
+        """Initialize the resource with an authenticated HTTP session."""
+        super().__init__(http, project_id=project_id)
+
+    def list(
+        self,
+        *,
+        search: str | None = None,
+        meteo_type: str | None = None,
+        page: int = 1,
+        size: int = 50,
+    ) -> Page:
+        """Return a paginated list of meteo locations."""
+        params: dict[str, Any] = {"page": page, "size": size}
+        if search is not None:
+            params["search"] = search
+        if meteo_type is not None:
+            params["meteo_type"] = meteo_type
+        return Page.model_validate(self._http.get("/meteo/locations", params=params))
+
+    def create(
+        self,
+        consumer: Consumer,
+        *,
+        project_id: str | None = None,
+        name: str | None = None,
+        meteo_type: str = "LOAD_CITY",
+        should_ingest_forecast: bool = True,
+    ) -> MeteoLocation:
+        """Create a meteorological location tied to a consumer's coordinates."""
+        pid = self._resolve_project_id(project_id)
+        payload = {
+            "latitude": consumer.latitude,
+            "longitude": consumer.longitude,
+            "name": name or f"{consumer.name} location",
+            "meteo_type": meteo_type,
+            "should_ingest_forecast": should_ingest_forecast,
+            "is_external": False,
+            "project_id": pid,
+        }
+        result = MeteoLocation.model_validate(self._http.post("/meteo/locations", json=payload))
+        self._log.info("Created meteo location (id=%s)", result.id)
+        return result
+
+    def ingest_historical(
+        self,
+        location: MeteoLocation,
+        start_date: datetime,
+        end_date: datetime,
+        *,
+        time_resolution: int = 15,
+    ) -> PendingJob[None]:
+        """Trigger historical meteo data ingestion; call .wait() on the result to sleep until done."""
+        payload = {
+            "start_date": start_date.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "end_date": end_date.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "time_resolution": time_resolution,
+        }
+        result = self._http.post(f"/meteo/locations/{location.id}/ingest-meteo", json=payload)
+        self._log.info("Historical meteo ingest submitted (task=%s)", result)
+
+        def _wait(_: int, timeout: int) -> None:
+            self._sleep(timeout, "historical meteo ingestion to complete")
+            self._log.info("historical meteo ingestion complete")
+
+        return PendingJob(result, wait_fn=_wait, poll_interval=0, timeout=600)

ogre_sdk/resources/meteo_sources.py

@@ -0,0 +1,19 @@
+"""Resource client for meteorological data sources."""
+
+from __future__ import annotations
+
+from .._http import _Session
+from .._resource import _BaseResource
+from ..models import MeteoSource
+
+
+class MeteoSources(_BaseResource):
+    """Browse available meteorological data sources."""
+
+    def __init__(self, http: _Session) -> None:
+        """Initialize the resource with an authenticated HTTP session."""
+        super().__init__(http)
+
+    def list(self) -> list[MeteoSource]:
+        """Return all meteo sources available to your project."""
+        return [MeteoSource.model_validate(s) for s in self._http.get("/meteo/sources")]

ogre_sdk/resources/training.py

@@ -0,0 +1,81 @@
+"""Resource client for model training."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .._http import _Session
+from .._resource import PendingJob, _BaseResource
+from ..models import Consumer, ForecastSettings, TrainedModel
+
+
+class Training(_BaseResource):
+    """Trigger and inspect demand forecast model training."""
+
+    def __init__(self, http: _Session, *, project_id: str | None = None) -> None:
+        """Initialize the resource with an authenticated HTTP session."""
+        super().__init__(http, project_id=project_id)
+
+    def get_model(
+        self,
+        consumer: Consumer,
+        forecast_settings: ForecastSettings,
+        *,
+        project_id: str | None = None,
+    ) -> TrainedModel:
+        """Return the trained model associated with a forecast settings object."""
+        pid = self._resolve_project_id(project_id)
+        path = (
+            f"/electricity/demand/{pid}/consumers/{consumer.id}"
+            f"/trained-models/by-forecast-settings/{forecast_settings.id}"
+        )
+        return TrainedModel.model_validate(self._http.get(path))
+
+    def run(
+        self,
+        consumer: Consumer,
+        forecast_settings: ForecastSettings,
+        start_date: datetime,
+        end_date: datetime,
+        *,
+        project_id: str | None = None,
+    ) -> PendingJob[dict[str, Any]]:
+        """Submit a training job; call .wait() on the result to block until the model is ready."""
+        pid = self._resolve_project_id(project_id)
+        payload = {
+            "start_date": start_date.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "end_date": end_date.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "forecast_settings_id": forecast_settings.id,
+        }
+        path = f"/electricity/demand/{pid}/consumers/{consumer.id}/train"
+        result = self._http.post(path, json=payload)
+        self._log.info("Training submitted (task=%s)", result)
+
+        start_naive = start_date.replace(tzinfo=None).isoformat()
+        end_naive = end_date.replace(tzinfo=None).isoformat()
+        model_path = (
+            f"/electricity/demand/{pid}/consumers/{consumer.id}"
+            f"/trained-models/by-forecast-settings/{forecast_settings.id}"
+        )
+
+        def _check_model() -> dict | None:
+            models = self._http.get(model_path)
+            if not isinstance(models, list):
+                models = [models]
+            for model in models:
+                interval = model.get("requested_interval")
+                if interval and interval[0] <= start_naive and interval[1] >= end_naive:
+                    self._log.info("Trained model found: %s", model["id"])
+                    return model
+            return None
+
+        def _wait(poll_interval: int, timeout: int) -> dict[str, Any]:
+            return self._poll(
+                _check_model,
+                poll_interval=poll_interval,
+                timeout=timeout,
+                description="model training",
+            )
+
+        return PendingJob(result, wait_fn=_wait, poll_interval=30, timeout=600)

ogre_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: ogre-sdk
+Version: 0.1.0
+Summary: Python SDK for the ogre.ai API
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: jupyterlab>=4.0; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'

ogre_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+ogre_sdk/__init__.py,sha256=wTYJ_3rHoxzFlGl3fPojoLAGP_WZx_cK9ARcquEy4Ns,1895
+ogre_sdk/_http.py,sha256=STr3DQKL_9N4v_Em-q2fizvXJsrWjXKKbmwV9oQ3aNk,1396
+ogre_sdk/_resource.py,sha256=nNtlpyCfT2YKWvvBSTQU7lCBIkhjejjQJLwE5PLjVAM,2667
+ogre_sdk/client.py,sha256=fmJc6OMalbcVCHPLR9HzKmL8QaTtjhWMqSXALg14dvQ,2589
+ogre_sdk/exceptions.py,sha256=iEUNQzrgYgXlfjy_KlPMY0BHF0A5SOieAWqk1D1t7FU,560
+ogre_sdk/models.py,sha256=-PhLn2ArcWsBH4i6iLOoDI37y7JGuYksMfBXspoH82Q,5936
+ogre_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ogre_sdk/resources/__init__.py,sha256=AJSB2M8sgfFFPxVgB0wYUmrp3RmJ4BZ1Q6RgQgcchUs,498
+ogre_sdk/resources/consumers.py,sha256=iHhVITSDLiCyVvWevQAsBVAl8gigAd0-0XU2WJMPn7I,9323
+ogre_sdk/resources/forecast_settings.py,sha256=dtbKsCSwQFRi-KkQZ6EzsWiAkzd2v23Tdd6oKOXVZao,2654
+ogre_sdk/resources/forecasts.py,sha256=fXl0D5RUF8spTCuA1mnVOmA9jk_YBdZBltE9bYDVA4M,2699
+ogre_sdk/resources/ingestion_settings.py,sha256=h2Iszb8VaSXTeEj55AzJubv2vFN5cP1EkBuTz3F1AWY,2138
+ogre_sdk/resources/meteo_locations.py,sha256=v5mVy2oU5sRVpXDZ50_rJKez17ei0EyIdvki6wJADVA,2972
+ogre_sdk/resources/meteo_sources.py,sha256=-7W2rMx_VZafBPePcGrx4aII8KefXyyrboBlXnu26JY,636
+ogre_sdk/resources/training.py,sha256=L4MCLNPsickNl7vfBHJgPYJ-8dRlhGh1n7b_0dyXGpk,3072
+ogre_sdk-0.1.0.dist-info/METADATA,sha256=zlGyd1xqCZyqldu14gm77xQVQO3crUiyP2oJDpKt3lQ,440
+ogre_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ogre_sdk-0.1.0.dist-info/RECORD,,

ogre_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any