Skip to content

api.md

Latest commit

 

History

History
156 lines (117 loc) · 3.27 KB

api.md

File metadata and controls

156 lines (117 loc) · 3.27 KB
Raw

API and Grafana Integration

helios_api.py exposes a first Helios-compatible planning API around the forecasting prototype.

The current pipeline is:

telemetry -> forecast -> optimizer -> policy checks -> scheduler/EMS/BMS integration

The integration stage is recommendation-only. It does not call a real scheduler, EMS, or BMS yet.

The API entrypoint is intentionally thin. Pipeline code is split by stage:

helios/ingest.py
helios/forecast.py
helios/optimizer.py
helios/policy.py
helios/integrations.py
helios/pipeline.py
helios/grafana.py
helios/api.py

Run

Install dependencies:

python3 -m pip install -r requirements.txt

Start the API:

uvicorn helios_api:app --reload --port 8000

OpenAPI docs are available at:

http://localhost:8000/docs

Run tests:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest -q

Endpoints

GET  /health
POST /api/v1/forecast
POST /api/v1/plan
POST /api/v1/grafana/timeseries
POST /search
POST /query
POST /annotations

/api/v1/forecast returns the preparation summary and forecast only.

/api/v1/plan returns the full pipeline:

  • preparation summary
  • forecast points
  • optimizer recommendations
  • policy check results
  • scheduler/EMS/BMS integration boundaries

/api/v1/grafana/timeseries returns Grafana-friendly target and datapoints JSON.

/search, /query, and /annotations implement the older Simple JSON style used by some Grafana data source plugins.

Example Request

curl -s http://localhost:8000/api/v1/plan \
  -H 'content-type: application/json' \
  -d '{
    "source": {
      "data": ["LST-E/smartmeterdata/*.csv"],
      "property": "power-total",
      "headerless": true,
      "max_rows": 50000
    },
    "forecast": {
      "horizon_steps": 24,
      "interval": "15min",
      "method": "rolling_mean",
      "rolling_window": 12
    },
    "optimizer": {
      "max_power": 4.0,
      "clean_power_available": 3.0,
      "prefer_clean_power": true,
      "shiftable_fraction": 0.25
    },
    "policy": {
      "allow_shift": true,
      "allow_site_move": false,
      "allow_storage_dispatch": false,
      "require_manual_approval": true
    }
  }'

Grafana Shape

For the JSON API or Infinity plugin, query:

POST http://localhost:8000/api/v1/grafana/timeseries

The response shape is:

[
  {
    "target": "power-total.forecast",
    "datapoints": [
      [1.23, 1710000000000]
    ]
  }
]

For a Simple JSON compatible plugin, configure:

http://localhost:8000

Then use targets:

power-total.forecast
optimizer.recommended_shift

Forecast Backend

The API currently uses a baseline forecast backend:

  • rolling_mean
  • last_value

This is intentional for the first API slice because it runs without TensorFlow or a saved model artifact. The LSTM training path remains in LST-E/LSTEnergy.py; the next step is to persist trained models and add a model_uri forecast backend.

Control Boundary

The API does not dispatch real workloads or change datacenter systems. It produces recommendations and policy decisions. Real integrations should be added as adapters behind the scheduler, EMS, and BMS boundaries after authentication, authorization, audit logging, and approval workflow are defined.