// 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 }