Files
api-go/internal/ml/client.go
T
Noel Sabia 7e9c2d9663
ci / check (push) Successful in 58s
ci / check (pull_request) Successful in 55s
feat: proxy PreZero priority endpoints to FastAPI
2026-11-14 17:50:53 +01:00

270 lines
9.0 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"`
}
// 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")
}
// 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
}