Phase 4 · API & Batch Integration

Priority: Medium Status: Pending Depends on: Phase 3 (trained model)

Context

• FastAPI service: kronos-service/main.py (port 8200)
• Batch script: scripts/kronos-batch-predict.py (hourly cron)
• Gateway cache: mcp-servers/gateway/src/handlers/ml-handlers.ts (4-tier lookup)

Overview

Wire event conditioning into the production pipeline. API accepts optional events. Batch script fetches calendar and builds event vectors. Gateway serves cached predictions unchanged.

Requirements

Functional

• /predict endpoint accepts optional events field
• /predict-batch passes events per symbol
• Batch script queries economic_calendar for upcoming events
• Event vectors aligned to OHLCV timestamps before calling Kronos
• Fallback: if events unavailable, use events=None (base model behavior)

Non-Functional

• No latency increase when events not provided
• Event vector construction <10ms per symbol
• Backward compatible — existing callers work without changes

Architecture

API Schema Change

schemas.py

class PredictRequest(BaseModel):
    symbol: str
    timeframe: str = "1d"
    pred_len: int = 120
    temperature: float = 1.0
    sample_count: int = 1
    lookback: int = 512
    as_of: Optional[str] = None
    events: Optional[List[List[float]]] = None  # NEW: (T, 20) or (T+pred_len, 20) — see phase-01

Batch Prediction Flow

1. Fetch OHLCV from Supabase (existing)
2. Fetch economic_calendar for lookback + prediction window (NEW)
3. Build event tensor via EventEncoder (NEW)
4. Call Kronos predictor with events=events_tensor (MODIFIED)
5. Compute envelope from samples (existing)
6. Insert into ml_predictions with event_context field (MODIFIED)

ml_predictions Schema Extension

ALTER TABLE ml_predictions ADD COLUMN IF NOT EXISTS
  event_context JSONB DEFAULT NULL;
-- Example: {"events_active": ["fomc"], "surprise_directions": {"fomc": "hawkish"}}

Implementation Steps

1. Modify kronos-service/main.py — accept events in /predict and /predict-batch
2. Modify kronos-service/main.py — load EventEncoder at startup alongside model
3. Modify scripts/kronos-batch-predict.py — fetch calendar data before prediction
4. Modify scripts/kronos-batch-predict.py — build event vectors per symbol
5. Modify scripts/kronos-batch-predict.py — include event_context in ml_predictions insert
6. Add migration: ml_predictions.event_context column
7. Test: batch prediction with and without events produces valid output
8. Test: API /predict with events=None returns same result as before

Key Files

• Modify: kronos-service/main.py — API endpoints
• Modify: scripts/kronos-batch-predict.py — batch pipeline
• Create: supabase/migrations/YYYYMMDD_ml_predictions_event_context.sql
• Read: kronos-service/db_loader.py (Supabase connection pattern)

Success Criteria

• API /predict with events returns predictions (no crash)
• API /predict without events returns identical results to current production
• Batch script completes for all 25 symbols in <5 minutes
• event_context populated in ml_predictions for event-day predictions
• Gateway continues serving cached predictions without changes