---
title: SuperAI Forecast
emoji: "📈"
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---
# SuperAI Forecast

SuperAI Forecast is a FastAPI + Lightweight Charts application for live market analysis with a multi-model AI forecast stack: Kronos, Google TimesFM, and Amazon Chronos.

## Core Features

- multi-source OHLCV data with automatic fallback
- technical indicator calculation
- independent Kronos / TimesFM / Chronos forecasting
- unified OHLC4 forecast contract across all AI models
- real-time WebSocket price streaming
- single-origin frontend served directly from the backend

## Runtime Requirements

- Windows with Python 3.11
- Internet access for market data
- Internet access on the first TimesFM model load if the checkpoint is not cached locally
- `ADMIN_TOKEN` must be configured before starting the backend

## Quick Start

```bat
run.bat
```

The launcher validates the virtual environment, ensures the local AI model dependencies are ready, applies the TimesFM compatibility patch, starts the backend, and opens the dashboard automatically.

On Windows, the launcher now prefers Opera first when opening the dashboard. If Opera is not installed, it falls back to the system default browser.

For a fresh clone or after AI dependency changes, run setup mode once:

```bat
run.bat --setup
```

## Manual Start

```bat
py -3.11 -m venv venv
venv\Scripts\python.exe -m pip install -r requirements.txt
copy .env.example .env
set ADMIN_TOKEN=replace-with-a-long-random-secret
run.bat --setup
venv\Scripts\python.exe -m backend.launcher
```

`requirements.txt` alone is not enough to guarantee TimesFM/Chronos readiness on a clean machine. `run.bat --setup` installs or refreshes the local model adapters under `libs/` and applies the TimesFM compatibility patch used by this app.

Use `.env.example` as the safe starting template for a new machine. Do not copy a live `.env` with real provider keys between repos or teammates.

If you move this repository to a new folder or clone it again elsewhere, rerun `run.bat --setup`. TimesFM is installed in editable mode, so a repo move can leave the venv pointing at the old path until setup refreshes it.

## Windows Startup

- The app registers a small launcher file in the current user's Windows `Startup` folder so `run.bat` opens automatically after sign-in.
- Legacy `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` entries are cleaned up automatically.
- This preference is enabled by default.
- If you want to change this behavior later, do it through the backend/system integration layer instead of the dashboard UI.

## Project Layout

```text
SuperAI Forecast/
|-- backend/
|   |-- main.py
|   |-- frontend_assets.py
|   |-- launcher.py
|   |-- server_runtime.py
|   |-- forecasting/
|   `-- startup_utils.py
|-- frontend/
|   |-- app.js
|   |-- forecast-models.js
|   |-- index.html
|   |-- workspace.js
|   `-- workspace.css
|-- libs/
|   `-- chronos-forecasting/
|-- scripts/
|   |-- check_timesfm_env.py
|   |-- patch_timesfm.py
|   `-- playwright_smoke.js
|-- requirements.txt
`-- run.bat
```

## Key Endpoints

- `GET /api/health`
- `GET /api/symbols`
- `GET /api/historical/{symbol}`
- `GET /api/indicators/{symbol}`
- `GET /api/forecast/{symbol}`
- `GET /api/market-status`
- `GET /api/crypto/market`
- `WS /ws/price/{symbol}`

## SuperAI Forecast Contract

- Input to every AI model is a single `OHLC4` series built as `(open + high + low + close) / 4`.
- The recommended context length is `512`, with model-specific fallback windows when the source history is shorter.
- The default horizon is `10`, so each enabled AI model predicts `T+1 ... T+10`.
- Output from each AI model is an independent future `OHLC4` line with quantiles `p10`, `p50`, `p90`.
- API responses expose both `last_close` (market close) and `last_ohlc4` (forecast baseline) so downstream analysis stays explicit and stable.
- Frontend rendering uses one forecast line per model, a shared horizon/timeframe contract, and a versioned asset registry for consistent model/UI alignment.

## Health Expectations

When the system is healthy:

- `/api/health` returns `status: online`
- `timesfm.available` is `true`
- `chronos.available` is `true`
- `kronos.available` is `true`
- each model reports its own readiness state after warmup or after the first forecast
- the frontend loads from the same backend origin

## Troubleshooting

- Install Python 3.11 if it is missing.
- Rebuild `venv` if it was copied from another machine.
- If startup stops immediately, confirm `ADMIN_TOKEN` is set in your shell or `.env`.
- If `timesfm.available` is `false`, rerun `run.bat --setup` to install the local TimesFM dependency and patch it for this project.
- If TimesFM worked before but suddenly reports `No module named 'timesfm'` after moving the repo, the editable install is still pointing at the old folder. Run `run.bat --setup` to repair the venv for the current path.
- If forecasts fail, check `/api/health` and confirm the target model is available and loaded.
- If market data fails, verify connectivity to Binance, Bybit, CoinGecko, Twelve Data, Finnhub, and Yahoo Finance.

## Local Verification

```bat
venv\Scripts\python.exe -m unittest discover -s backend -p "test_*.py"
npm install
node --check frontend\app.js
node --check frontend\workspace.js
node scripts\playwright_smoke.js
```