314 lines
11 KiB
Go
314 lines
11 KiB
Go
// Package ml is the FastAPI client. Prediction calls use the caller's deadline
|
|
// (1.5 s by default); callers fall back to the last good forecast on any error.
|
|
// The larger /bootstrap snapshot gets its own, longer transport timeout.
|
|
package ml
|
|
|
|
import (
|
|
"bytes"
|
|
"context"
|
|
"encoding/json"
|
|
"fmt"
|
|
"io"
|
|
"net/http"
|
|
"net/url"
|
|
"strconv"
|
|
"strings"
|
|
"time"
|
|
|
|
"pulsecast/api/internal/model"
|
|
)
|
|
|
|
// DefaultTimeout is the contract limit for a live prediction.
|
|
const DefaultTimeout = 1500 * time.Millisecond
|
|
|
|
// controlTimeout bounds training submissions and status reads. Uploads are
|
|
// larger than prediction payloads, so they get more than DefaultTimeout.
|
|
const controlTimeout = 30 * time.Second
|
|
|
|
// bootstrapTimeout is the upper transport bound for the /bootstrap snapshot,
|
|
// which carries the full hourly series for every sensor.
|
|
const bootstrapTimeout = 30 * time.Second
|
|
|
|
// Client talks to the FastAPI ML service.
|
|
type Client struct {
|
|
baseURL string
|
|
http *http.Client
|
|
control *http.Client
|
|
bootstrap *http.Client
|
|
controlToken string
|
|
}
|
|
|
|
// New returns a client for baseURL (for example http://localhost:8000).
|
|
func New(baseURL string, timeout time.Duration) *Client {
|
|
return NewWithToken(baseURL, timeout, "")
|
|
}
|
|
|
|
// NewWithToken is New plus the Bearer token FastAPI's internal /train
|
|
// endpoints expect. An empty token sends no Authorization header.
|
|
func NewWithToken(baseURL string, timeout time.Duration, controlToken string) *Client {
|
|
if timeout <= 0 {
|
|
timeout = DefaultTimeout
|
|
}
|
|
return &Client{
|
|
baseURL: strings.TrimRight(baseURL, "/"),
|
|
http: &http.Client{Timeout: timeout},
|
|
control: &http.Client{Timeout: controlTimeout},
|
|
bootstrap: &http.Client{Timeout: bootstrapTimeout},
|
|
controlToken: controlToken,
|
|
}
|
|
}
|
|
|
|
// Bootstrap fetches GET /bootstrap, the runtime snapshot the API caches. The
|
|
// caller supplies the shorter request deadline; this method only validates the
|
|
// transport response and that the snapshot is usable.
|
|
func (c *Client) Bootstrap(ctx context.Context) (model.Bootstrap, error) {
|
|
var out model.Bootstrap
|
|
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/bootstrap", nil)
|
|
if err != nil {
|
|
return out, fmt.Errorf("ml: build request: %w", err)
|
|
}
|
|
req.Header.Set("Accept", "application/json")
|
|
|
|
resp, err := c.bootstrap.Do(req)
|
|
if err != nil {
|
|
return out, fmt.Errorf("ml: /bootstrap: %w", err)
|
|
}
|
|
defer resp.Body.Close()
|
|
|
|
if resp.StatusCode < 200 || resp.StatusCode > 299 {
|
|
snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 256))
|
|
return out, fmt.Errorf("ml: /bootstrap: status %d: %s", resp.StatusCode, strings.TrimSpace(string(snippet)))
|
|
}
|
|
raw, err := io.ReadAll(io.LimitReader(resp.Body, 64<<20))
|
|
if err != nil {
|
|
return out, fmt.Errorf("ml: read /bootstrap: %w", err)
|
|
}
|
|
if err := json.Unmarshal(raw, &out); err != nil {
|
|
return out, fmt.Errorf("ml: decode /bootstrap: %w", err)
|
|
}
|
|
if len(out.Sensors) == 0 {
|
|
return out, fmt.Errorf("ml: /bootstrap returned no sensors")
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// PredictRequest mirrors the API contract POST /predict.
|
|
type PredictRequest struct {
|
|
Sensor string `json:"sensor"`
|
|
Horizon string `json:"horizon"`
|
|
Scenario string `json:"scenario"`
|
|
Weather WeatherInput `json:"weather"`
|
|
IsHoliday bool `json:"is_holiday"`
|
|
}
|
|
|
|
// WeatherInput is the optional weather block.
|
|
type WeatherInput struct {
|
|
TempC float64 `json:"temp_c"`
|
|
PrecipMM float64 `json:"precip_mm"`
|
|
}
|
|
|
|
// PlaygroundWeather is the optional absolute weather override for the
|
|
// playground. Pointers distinguish "not supplied" from a real zero value.
|
|
type PlaygroundWeather struct {
|
|
TempC *float64 `json:"temp_c,omitempty"`
|
|
PrecipMM *float64 `json:"precip_mm,omitempty"`
|
|
}
|
|
|
|
// PlaygroundRequest is the public playground's prediction request. Weather is
|
|
// omitted entirely when the caller did not override it, so Python uses its
|
|
// baked hourly weather forecast.
|
|
type PlaygroundRequest struct {
|
|
Sensor string `json:"sensor"`
|
|
Horizon string `json:"horizon"`
|
|
Scenario string `json:"scenario"`
|
|
Weather *PlaygroundWeather `json:"weather,omitempty"`
|
|
IsHoliday *bool `json:"is_holiday,omitempty"`
|
|
}
|
|
|
|
// PlaygroundResponse mirrors the subset of FastAPI POST /predict that the
|
|
// playground returns to the browser.
|
|
type PlaygroundResponse struct {
|
|
Sensor string `json:"sensor"`
|
|
Horizon string `json:"horizon"`
|
|
Scenario string `json:"scenario"`
|
|
Points []model.ForecastPoint `json:"points"`
|
|
DataVersion string `json:"data_version"`
|
|
ModelVersion string `json:"model_version"`
|
|
ContextVersion string `json:"context_version"`
|
|
}
|
|
|
|
// SimulateRequest mirrors the API contract POST /simulate.
|
|
type SimulateRequest struct {
|
|
Scenario string `json:"scenario"`
|
|
Weather model.WeatherInput `json:"weather"`
|
|
Sensors string `json:"sensors"`
|
|
}
|
|
|
|
// TrainRequest is the JSON form of POST /train.
|
|
type TrainRequest struct {
|
|
Path string `json:"path"`
|
|
Model string `json:"model"`
|
|
}
|
|
|
|
// TrainModels are the accepted training targets.
|
|
var TrainModels = []string{"small", "forecast"}
|
|
|
|
// Predict calls POST /predict and returns the forecast points. The contract
|
|
// response is {"points":[...]}; a bare array is accepted as well.
|
|
func (c *Client) Predict(ctx context.Context, req PredictRequest) ([]model.ForecastPoint, error) {
|
|
raw, err := c.postRaw(ctx, "/predict", req)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
var out struct {
|
|
Points []model.ForecastPoint `json:"points"`
|
|
}
|
|
if err := json.Unmarshal(raw, &out); err == nil && out.Points != nil {
|
|
if len(out.Points) == 0 {
|
|
return nil, fmt.Errorf("ml: predict returned no points")
|
|
}
|
|
return out.Points, nil
|
|
}
|
|
|
|
var points []model.ForecastPoint
|
|
if err := json.Unmarshal(raw, &points); err == nil && len(points) > 0 {
|
|
return points, nil
|
|
}
|
|
return nil, fmt.Errorf("ml: predict returned no points")
|
|
}
|
|
|
|
// PlaygroundPredict calls POST /predict with optional weather and holiday
|
|
// overrides. Unlike Predict it preserves the response versions for the public
|
|
// playground.
|
|
func (c *Client) PlaygroundPredict(ctx context.Context, req PlaygroundRequest) (PlaygroundResponse, error) {
|
|
var out PlaygroundResponse
|
|
if err := c.post(ctx, "/predict", req, &out); err != nil {
|
|
return out, err
|
|
}
|
|
if len(out.Points) == 0 {
|
|
return out, fmt.Errorf("ml: playground predict returned no points")
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// Simulate calls POST /simulate and returns forecasts keyed
|
|
// sensor -> horizon -> points.
|
|
func (c *Client) Simulate(ctx context.Context, req SimulateRequest) (map[string]map[string][]model.ForecastPoint, error) {
|
|
var out struct {
|
|
Scenario string `json:"scenario"`
|
|
Generated string `json:"generated_at"`
|
|
Forecasts map[string]map[string][]model.ForecastPoint `json:"forecasts"`
|
|
}
|
|
if err := c.post(ctx, "/simulate", req, &out); err != nil {
|
|
return nil, err
|
|
}
|
|
if len(out.Forecasts) == 0 {
|
|
return nil, fmt.Errorf("ml: simulate returned no forecasts")
|
|
}
|
|
return out.Forecasts, nil
|
|
}
|
|
|
|
// Train proxies POST /train. body is forwarded verbatim (JSON or multipart),
|
|
// and the upstream status and response are returned unchanged for the Go
|
|
// handler to relay. Training itself runs in FastAPI; this call only queues it.
|
|
func (c *Client) Train(ctx context.Context, contentType string, body io.Reader) (int, []byte, error) {
|
|
return c.controlRequest(ctx, http.MethodPost, "/train", contentType, body)
|
|
}
|
|
|
|
// TrainStatus proxies GET /train/{job_id}.
|
|
func (c *Client) TrainStatus(ctx context.Context, jobID string) (int, []byte, error) {
|
|
return c.controlRequest(ctx, http.MethodGet, "/train/"+url.PathEscape(jobID), "", nil)
|
|
}
|
|
|
|
// PreZeroSummary proxies GET /prezero/summary.
|
|
func (c *Client) PreZeroSummary(ctx context.Context) (int, []byte, error) {
|
|
return c.controlRequest(ctx, http.MethodGet, "/prezero/summary", "", nil)
|
|
}
|
|
|
|
// PreZeroPriority proxies GET /prezero/priority. priority may be empty to
|
|
// return every tier; limit and offset are always forwarded.
|
|
func (c *Client) PreZeroPriority(ctx context.Context, priority string, limit, offset int) (int, []byte, error) {
|
|
query := url.Values{}
|
|
if priority != "" {
|
|
query.Set("priority", priority)
|
|
}
|
|
query.Set("limit", strconv.Itoa(limit))
|
|
query.Set("offset", strconv.Itoa(offset))
|
|
return c.controlRequest(ctx, http.MethodGet, "/prezero/priority?"+query.Encode(), "", nil)
|
|
}
|
|
|
|
// PreZeroContainer proxies GET /prezero/containers/{location_id}.
|
|
func (c *Client) PreZeroContainer(ctx context.Context, locationID string) (int, []byte, error) {
|
|
return c.controlRequest(ctx, http.MethodGet, "/prezero/containers/"+url.PathEscape(locationID), "", nil)
|
|
}
|
|
|
|
// controlRequest performs a training/control request and returns the raw
|
|
// upstream status and body. Non-2xx responses are not errors: the proxy
|
|
// forwards them so clients see FastAPI's 400/404/409 semantics.
|
|
func (c *Client) controlRequest(ctx context.Context, method, path, contentType string, body io.Reader) (int, []byte, error) {
|
|
req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, body)
|
|
if err != nil {
|
|
return 0, nil, fmt.Errorf("ml: build request: %w", err)
|
|
}
|
|
if contentType != "" {
|
|
req.Header.Set("Content-Type", contentType)
|
|
}
|
|
req.Header.Set("Accept", "application/json")
|
|
if c.controlToken != "" {
|
|
req.Header.Set("Authorization", "Bearer "+c.controlToken)
|
|
}
|
|
|
|
resp, err := c.control.Do(req)
|
|
if err != nil {
|
|
return 0, nil, fmt.Errorf("ml: %s: %w", path, err)
|
|
}
|
|
defer resp.Body.Close()
|
|
|
|
raw, err := io.ReadAll(io.LimitReader(resp.Body, 32<<20))
|
|
if err != nil {
|
|
return 0, nil, fmt.Errorf("ml: read %s: %w", path, err)
|
|
}
|
|
return resp.StatusCode, raw, nil
|
|
}
|
|
|
|
func (c *Client) post(ctx context.Context, path string, body, dst any) error {
|
|
raw, err := c.postRaw(ctx, path, body)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if err := json.Unmarshal(raw, dst); err != nil {
|
|
return fmt.Errorf("ml: decode %s: %w", path, err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func (c *Client) postRaw(ctx context.Context, path string, body any) ([]byte, error) {
|
|
raw, err := json.Marshal(body)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("ml: encode request: %w", err)
|
|
}
|
|
req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, bytes.NewReader(raw))
|
|
if err != nil {
|
|
return nil, fmt.Errorf("ml: build request: %w", err)
|
|
}
|
|
req.Header.Set("Content-Type", "application/json")
|
|
req.Header.Set("Accept", "application/json")
|
|
|
|
resp, err := c.http.Do(req)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("ml: %s: %w", path, err)
|
|
}
|
|
defer resp.Body.Close()
|
|
|
|
if resp.StatusCode < 200 || resp.StatusCode > 299 {
|
|
snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 256))
|
|
return nil, fmt.Errorf("ml: %s: status %d: %s", path, resp.StatusCode, strings.TrimSpace(string(snippet)))
|
|
}
|
|
raw, err = io.ReadAll(io.LimitReader(resp.Body, 32<<20))
|
|
if err != nil {
|
|
return nil, fmt.Errorf("ml: read %s: %w", path, err)
|
|
}
|
|
return raw, nil
|
|
}
|