// Package ml is the FastAPI client. Every call is bounded by a 1.5 s timeout; // callers fall back to baked JSON on any error. package ml import ( "bytes" "context" "encoding/json" "fmt" "io" "net/http" "net/url" "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 // Client talks to the FastAPI ML service. type Client struct { baseURL string http *http.Client control *http.Client } // New returns a client for baseURL (for example http://localhost:8000). func New(baseURL string, timeout time.Duration) *Client { if timeout <= 0 { timeout = DefaultTimeout } return &Client{ baseURL: strings.TrimRight(baseURL, "/"), http: &http.Client{Timeout: timeout}, control: &http.Client{Timeout: controlTimeout}, } } // PredictRequest mirrors CONTRACT.md §3 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 CONTRACT.md §3 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 from CONTRACT.md §3. 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) } // 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") 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 }