# AI Forecast Workflow

Tai lieu nay mo ta ro luong hoat dong, nguyen tac tach lop, va cong thuc tinh diem hien tai cua he thong.

## 1. Muc tieu kien truc

- Frontend chi render va dieu phoi request.
- Backend la single source of truth cho moi phep tinh.
- PTKT, AI Forecast, tung AI model deu doc lap.
- Don pane va da pane dung chung 1 pipeline, 1 cong thuc, 1 luong huy request.
- Khi doi symbol, timeframe, layout, pane mode: request cu phai bi huy ngay.

## 2. Nguyen tac bat buoc

### 2.1. Frontend

- Khong tinh gauge.
- Khong tinh certainty.
- Khong tu gop forecast.
- Khong tu tinh summary.
- Chi doc payload backend va hien thi.

### 2.2. PTKT

- PTKT chi dua tren indicator va moving average.
- Khong bi AI Forecast tac dong.
- So sanh bang raw value, khong duoc lam tron roi moi so sanh.
- Gia tri hien thi duoc format rieng de UI de doc, nhung logic xep loai van dung raw value.

### 2.3. AI Forecast

- Moi model AI phan tich doc lap tren cung mot chuoi OHLC4.
- Cac model khong duoc anh huong qua lai.
- Top-level AI chi tong hop bang trung binh cong ket qua cua cac model dang bat.

### 2.4. Du lieu FX va Real Strength

- Toan bo cap FX uu tien `Twelve Data`, chi fallback sang `yfinance` khi can.
- Cac ma `USDX/EURX/GBPX/CHFX/JPYX/CADX/AUDX/NZDX` chi duoc dung cap thanh phan truc tiep hoac nghich dao truc tiep.
- Khong duoc quay lai cong thuc tu dung kieu `EURCHF = EURUSD * USDCHF`.
- Khi tinh Real Strength:
  - uu tien dung cung nguon cho toan bo basket
  - neu cung nguon khong du nen khop thi duoc phep tron nguon
  - thu tu uu tien van la `Twelve Data -> yfinance`
- Cache phai tai su dung du lieu component da co de giam toi da credit Twelve Data.

## 3. Luong hoat dong chung

```mermaid
flowchart TD
    A["User doi symbol / timeframe / layout / pane mode"] --> B["Abort fetchController + analysisFetchController"]
    B --> C["loadPaneData(pane)"]
    C --> D["Nap historical + indicators"]
    D --> E["PaneState.fetchAI()"]
    E --> F["GET /api/forecast/{symbol}?interval=...&horizon=...&models=..."]
    F --> G["Backend chon 1 shared_context_length cho toan bo model dang bat"]
    G --> H["Moi model forecast doc lap tren cung luong OHLC4"]
    H --> I["Backend tinh PTKT rieng"]
    H --> J["Backend tinh AI gauge/certainty rieng tung model"]
    J --> K["Top-level AI = mean(model gauges) + mean(model certainty)"]
    I --> L["Summary = (Gauge PTKT + Gauge AI) / 2"]
    K --> L
    L --> M["Frontend render payload"]
    M --> N["connectPaneWS(pane) / connectWS -> pane-0"]
```

## 4. Shared context cho AI

Tat ca model dang bat phai dung cung:

- cung symbol
- cung interval
- cung horizon
- cung chuoi input OHLC4 thô
- cung `shared_context_length`

Mac dinh hien tai:

- `DEFAULT_FORECAST_MODEL_CONTEXT = 512`
- backend uu tien danh gia cac candidate den toi da `512` neu lich su du
- synthetic symbol khong duoc lam tron `open/high/low/close` truoc khi tao chuoi `OHLC4`

Cong thuc chon:

```text
shared_context_cap =
  min(model_context_cap cua tung model dang bat)

shared_context_length =
  argmax_context_len(
    market_texture_score(context_len)
  )
  voi context_len <= shared_context_cap
```

Y nghia:

- Chieu dai context duoc chon boi market-driven heuristic, khong boi model output.
- Sau khi chon xong, moi model deu nhan cung mot so luong nen OHLC4.
- Chuoi OHLC4 dau vao luon di tu gia nguon dang float, khong lam tron som de tranh mat thong tin.
- Neu model nao khong chiu duoc context nay thi coi nhu loi pipeline, khong am tham tu rut gon rieng.

## 5. Cong thuc PTKT

## 5.1. Dau vao

- Oscillator data
- Performance data theo N nen: `1, 2, 3, 5, 7, 30, 90, 180, 365`
  - Rieng `Hieu suat 2 nen` duoc tinh `2` phieu cho nhom Performance
- EMA pair data
- Tat ca deu lay raw value moi nhat, khong lam tron truoc khi xep loai

## 5.2. Xep loai Moving Average

Thay vi so sanh gia tri da round, he thong so sanh spread phan tram raw:

```text
spread_pct = pct(fast_ema, slow_ema)
neutral_band_pct = max(pair_threshold_pct * 0.08, 0.0005)

neu spread_pct > neutral_band_pct  -> Mua
neu spread_pct < -neutral_band_pct -> Ban
con lai                           -> Trung lap
```

Dieu nay giai quyet truong hop ma gia rat nho nhu 0.294 va 0.296:

- UI co the hien cung 0.29 neu format ngan
- nhung logic van thay raw spread va khong bi ep thanh trung lap oan

## 5.3. Nhom Oscillator

Oscillator bay gio chi con la **nhom phan loai**:

- moi dong co `action`: `Mua / Ban / Trung lap`
- backend dem tong `buy / sell / neutral`
- backend van giu `signal` cap nhom de phuc vu cache verdict va hien thi

Khong con khai niem `Gauge Oscillator` rieng.

## 5.4. Nhom Moving Average

Moving Average cung chi la **nhom phan loai**:

- moi cap EMA co `action`: `Mua / Ban / Trung lap`
- backend dem tong `buy / sell / neutral`
- backend giu `signal`, `golden_cross`, `death_cross`

Khong con khai niem `Gauge Moving Average` rieng.

## 5.5. Nhom Hieu suat

Hieu suat la **nhom phan loai** thu 3:

- moi dong so sanh `OHLC4 hien tai` voi `OHLC4 cua N nen truoc`
- cong thuc:

```text
ohlc4 = (open + high + low + close) / 4
change_pct = ((ohlc4_hien_tai / ohlc4_n_nen_truoc) - 1) * 100
```

- neu `change_pct > 0`  -> `Mua`
- neu `change_pct < 0`  -> `Ban`
- neu `change_pct = 0`  -> `Trung lap`
- neu thieu du lieu hoac `ohlc4_tham_chieu = 0` -> `N/A`, khong tinh vao vote

Luu y:

- day la **N nen**, khong phai N ngay co dinh
- nghia la o timeframe `1h` thi `30` tuc la `30 nen 1h`
- o timeframe `1d` thi `30` tuc la `30 nen ngay`

## 5.6. Gauge PTKT

Gauge PTKT duoc tinh truc tiep tu tong phieu cua **ca 3 nhom**:

```text
B = mua_oscillator + mua_performance + mua_moving_average
S = ban_oscillator + ban_performance + ban_moving_average
N = trung_lap_oscillator + trung_lap_performance + trung_lap_moving_average
T = B + S + N

Gauge PTKT
= 50 + 50 * (B - S)/T * (B + S)/T * 1/(1 + e^(-(ADX10 - 20)/8))
```

Trong do:

- dang phan so de de doc:

```text
Gauge PTKT
= 50 + [50 * (B - S) * (B + S)] / T^2 * 1/(1 + e^(-(ADX10 - 20)/8))
```

- ADX dung chu ky `10`
- sigmoid kich hoat xu huong la:

```text
1 / (1 + e^(-(ADX10 - 20)/8))
```

- cac dong `N/A` cua nhom Hieu suat bi loai khoi vote, khong cong vao `B`, `S`, hay `N`
- trong nhom Hieu suat, dong `Hieu suat 2 nen` duoc cong `2` phieu vao `B`, `S`, hoac `N` tuy theo action

Khong chen AI vao PTKT.

## 6. Cong thuc AI Forecast

## 6.1. Metric full-path cua moi model

Tu `p50_path`:

- `weighted_return_pct`
- `final_return_pct`
- `path_consistency`
- `monotonicity`
- `max_adverse_excursion_pct`

Tu `p10/p50/p90`:

- `avg_band_pct`
- `end_band_pct`
- `band_stability_pct`
- `band_step_change_pct`

## 6.2. Do chac chan cua moi model

```text
avg_band_tightness =
  exp(-avg_band_pct / max(ATR% * 3.0, 0.75))

end_band_tightness =
  exp(-end_band_pct / max(ATR% * 3.4, 0.85))

band_stability_score =
  exp(-(
    band_stability_pct / max(ATR% * 1.8, 0.35) +
    band_step_change_pct / max(ATR% * 1.2, 0.25)
  ) * 0.75)

adverse_control_score =
  exp(-max_adverse_excursion_pct / max(ATR% * 2.5, 0.8))

certainty_model =
  clamp(
    0.38 * avg_band_tightness +
    0.16 * end_band_tightness +
    0.16 * band_stability_score +
    0.15 * path_consistency +
    0.10 * monotonicity +
    0.05 * adverse_control_score,
    0.08,
    0.98
  ) * 100
```

## 6.3. Gauge cua moi model

```text
directional_edge_pct =
  0.70 * weighted_return_pct +
  0.30 * final_return_pct

direction_norm =
  tanh(directional_edge_pct / max(ATR% * 1.35, 0.35))

path_move_score =
  tanh((
    0.65 * abs(weighted_return_pct) / ATR% +
    0.35 * abs(final_return_pct) / ATR%
  ) / 1.7)

path_quality =
  0.48 +
  0.30 * path_consistency +
  0.22 * monotonicity

certainty_factor =
  0.52 + 0.48 * certainty_model

Gauge model =
  clamp(
    50 +
    direction_norm *
    (14 + 20 * path_move_score) *
    path_quality *
    certainty_factor,
    8,
    92
  )
```

Luu y:

- Gauge AI chi do huong + do manh cua duong forecast.
- PTKT khong chen vao gauge AI.

## 6.4. Tong hop nhieu model

Neu bat `n` model:

```text
Gauge AI top-level     = mean(gauge_model_1 ... gauge_model_n)
Do chac chan top-level = mean(certainty_model_1 ... certainty_model_n)
```

Duong forecast top-level van la:

```text
combined_p10 = mean(p10_model_i)
combined_p50 = mean(p50_model_i)
combined_p90 = mean(p90_model_i)
```

Nhung:

- moi model tu forecast rieng
- moi model tu score rieng
- top-level chi mean ket qua, khong ep model nay sua theo model kia

## 7. Gauge Tong ket

```text
Gauge Tong ket = (Gauge PTKT + Gauge Du bao AI) / 2
```

Khong weighting theo certainty.
Khong pull-to-neutral theo AI certainty.
Khong tron cong thuc rieng o frontend.

## 8. Huy request cu

Moi pane co:

- `fetchController`
- `analysisFetchController`

Moi lan doi:

- symbol
- timeframe
- layout
- don pane / da pane

he thong se:

1. `abort()` request cu ngay lap tuc
2. reset state dang cho cua pane
3. mo request moi theo context moi

Ket qua:

- khong phai doi ma cu load xong moi toi ma moi
- khong bi ket hang request
- single-pane va multi-pane dung cung 1 co che

## 9. Don pane va da pane dung chung nhung gi

| Thanh phan | Single-pane | Multi-pane |
| --- | --- | --- |
| Nap historical + indicators | `loadPaneData(pane-0)` | `loadPaneData(pane)` |
| Nap AI forecast | `PaneState.fetchAI()` | `PaneState.fetchAI()` |
| API AI | `/api/forecast/...` | `/api/forecast/...` |
| Tinh PTKT | Backend | Backend |
| Tinh AI gauge/certainty | Backend | Backend |
| Tinh summary | Backend | Backend |
| Realtime | `connectWS()` -> `connectPaneWS(pane-0)` | `connectPaneWS(pane)` |
| Huy request | `resetPendingPaneAI(pane-0)` | `resetPendingPaneAI(pane)` |

## 10. Metadata quan sat

Backend gan them:

- `analysis.scoring.version`
- `analysis.scoring.technical_version`
- `analysis.scoring.shared_context_length`
- `analysis.scoring.shared_context_cap`
- `analysis.ai_models.formula_version`
- `analysis.ai_models.shared_context`

Muc dich:

- cache dung version cong thuc moi
- de debug nhanh context chung giua cac model
- de kiem tra frontend chi dang hien thi payload backend

## 11. Tom tat nhanh

- Frontend chi hien thi, backend tinh toan.
- PTKT va AI doc lap.
- Cac model AI doc lap va cung dung 1 `shared_context_length`.
- Gauge AI top-level = trung binh cong gauge model dang bat.
- Do chac chan top-level = trung binh cong certainty model dang bat.
- Gauge Tong ket = `(PTKT + AI) / 2`.
- PTKT khong so sanh tren gia tri da lam tron.
- Don pane va da pane dung chung 1 pipeline.