Hiroaki86
203 lines
8.0 KiB
Markdown
203 lines
8.0 KiB
Markdown
# ea_py
|
||
|
||
MT5 の HIT-EA から出力された OHLC CSV を読み取り、GOLD/XAUUSD 向けの相場環境判定とエントリー候補価格を返す Python 補助アプリケーションです。
|
||
|
||
Python 側は注文送信を行いません。発注、注文管理、M15 確定足による最終タイミング判定は MT5/MQL5 EA 側が担当します。
|
||
|
||
## 現在の実行入口
|
||
|
||
MT5 EA からは `bat/` 経由でルート直下の互換スクリプトを起動します。
|
||
|
||
```text
|
||
<TerminalDataPath>/MQL5/python_for_ea/
|
||
├─ get_trend_reply.py
|
||
├─ get_entry_reply.py
|
||
├─ bat/
|
||
│ ├─ get_trend_reply.bat
|
||
│ └─ get_entry_reply.bat
|
||
└─ src/
|
||
└─ ea_py/
|
||
```
|
||
|
||
- `get_trend_reply.py`: `src/ea_py/pipelines/trend_pipeline.py` を起動する薄い入口。
|
||
- `get_entry_reply.py`: `src/ea_py/pipelines/entry_pipeline.py` を起動する薄い入口。
|
||
- `bat/get_trend_reply.bat`: bat自身の親フォルダをプロジェクトルートとして `uv run python get_trend_reply.py` を実行。
|
||
- `bat/get_entry_reply.bat`: bat自身の親フォルダをプロジェクトルートとして `uv run python get_entry_reply.py` を実行。
|
||
|
||
入口ファイル名や配置を変える場合は、`bat/` と MQL5 EA 側の呼び出し設定も合わせて更新してください。
|
||
|
||
## MT5 連携ファイル
|
||
|
||
既定の連携先は、このプロジェクトの親にある MT5 `MQL5/Files` ディレクトリです。
|
||
|
||
```text
|
||
<TerminalDataPath>/MQL5/Files/
|
||
```
|
||
|
||
パスの組み立ては `src/ea_py/paths.py` で定義しています。特殊な配置では `MT5_FILES_DIR` または `MT5_DATA_PATH` 環境変数で上書きできます。
|
||
|
||
EAからbat経由で起動する場合は、第1引数で渡された `HIT_<symbol>_<magic_number>` 接頭辞が `MT5_EA_FILE_PREFIX` として設定されます。第2引数で渡された `_Symbol` の価格桁数は `MT5_PRICE_DIGITS` として設定されます。Pythonはこの接頭辞をすべての連携ファイル名へ付けるため、同じTerminal内で複数EAや複数シンボルを動かしてもファイルが衝突しません。手動実行で接頭辞が未設定の場合は、従来のファイル名を使います。
|
||
|
||
### 入力
|
||
|
||
```text
|
||
[<prefix>_]ohlc_H4.csv
|
||
[<prefix>_]ohlc_H1.csv
|
||
```
|
||
|
||
CSV は UTF-8 読み込みで、次の列を必須とします。価格列はfloatへ変換し、NaN/infや `High < Low`、High/LowがOpen/Closeを含まない行は停止値へ倒すため例外にします。
|
||
|
||
```text
|
||
Time,Open,High,Low,Close
|
||
```
|
||
|
||
### 出力
|
||
|
||
```text
|
||
[<prefix>_]trend_state.txt
|
||
[<prefix>_]target_prices.txt
|
||
[<prefix>_]target_zones.txt
|
||
[<prefix>_]process_done_trend.txt
|
||
[<prefix>_]process_done_entry.txt
|
||
```
|
||
|
||
MT5 が読む結果ファイルは `utf-16 LE` で出力します。結果ファイルを書き終えたあとに done ファイルを作成します。古い done ファイルは結果書き込み前に削除されます。
|
||
|
||
## H4 トレンド判定
|
||
|
||
`get_trend_reply.py` は H4 OHLC から `trend_state.txt` を生成します。
|
||
|
||
現在の H4 判定は OpenAI API ではなく、ソースコード上のルールベース判定です。直近 72 本を使い、EMA、レンジ内位置、高安更新、DMI 系方向優位、効率比、EATR ベースのボラティリティを組み合わせて `market_state` を決定します。
|
||
|
||
```text
|
||
0 = LOW_VOL_RANGE
|
||
1 = HIGH_VOL_RANGE
|
||
2 = LOW_VOL_UP
|
||
3 = HIGH_VOL_UP
|
||
4 = LOW_VOL_DOWN
|
||
5 = HIGH_VOL_DOWN
|
||
6 = TECHNICAL_ERROR_STOP
|
||
```
|
||
|
||
`6` は現在の実装では技術エラー停止値です。CSV 読み込み失敗、データ不足、EATR 異常値など、安全側へ倒す必要がある場合に出力されます。
|
||
|
||
## H1 エントリー候補生成
|
||
|
||
`get_entry_reply.py` は `trend_state.txt` と H1 OHLC から `target_prices.txt` と `target_zones.txt` を生成します。
|
||
|
||
処理の概要:
|
||
|
||
1. H4 の `market_state` を読み込む。
|
||
2. `market_state` と整合する戦略だけを選ぶ。
|
||
3. H1 の短期 36 本、中期 72 本からチャート PNG と数値要約を作る。
|
||
4. H1 インバランス初動を Python 側で判定し、矛盾する候補を抑止する。
|
||
5. OpenAI Responses API に候補価格・予測ゾーン生成を依頼する。
|
||
6. GPT 出力を既存13行形式と分割エントリー用ゾーン形式へ展開し、価格の大小関係と距離を検証する。
|
||
7. `target_prices.txt` と `target_zones.txt` を書き、両方の完了後に `process_done_entry.txt` を作成する。
|
||
|
||
H4 状態ごとの許可戦略:
|
||
|
||
```text
|
||
0,1: T2 Buy Limit / T4 Sell Limit
|
||
2,3: T1 Buy Stop / T2 Buy Limit
|
||
4,5: T3 Sell Stop / T4 Sell Limit
|
||
6 : 全停止
|
||
```
|
||
|
||
`target_prices.txt` は 13 行です。
|
||
|
||
```text
|
||
1行目 : res_chk
|
||
2-4行目 : T1 Buy Stop の entry, tp, sl
|
||
5-7行目 : T2 Buy Limit の entry, tp, sl
|
||
8-10行目 : T3 Sell Stop の entry, tp, sl
|
||
11-13行目 : T4 Sell Limit の entry, tp, sl
|
||
```
|
||
|
||
有効候補が残らない場合や、CSV/API/パース/検証に失敗した場合は、13 行すべて `0` の停止値を返します。
|
||
|
||
分割エントリー用の `target_zones.txt` は7行です。
|
||
|
||
```text
|
||
1行目 : schema_version（2）
|
||
2行目 : res_chk
|
||
3行目 : candidate_id（H1確定足時刻由来）
|
||
4-7行目 : strategy, zone_low, zone_high, tp, sl
|
||
```
|
||
|
||
EA側で分割エントリーを有効にした場合は、この予測ゾーンを `split_entry_count` 本に分割してpending注文を出します。ロットは総量分割または1注文固定を選択できます。
|
||
|
||
`target_zones.txt` の価格小数桁は `MT5_PRICE_DIGITS` に合わせます。EA/bat経由では自動設定され、手動実行で未指定の場合は安全側で5桁を使います。
|
||
|
||
## OpenAI 設定
|
||
|
||
H1 エントリー候補生成では OpenAI API を使用します。
|
||
|
||
必須:
|
||
|
||
```powershell
|
||
$env:OPENAI_API_KEY = "..."
|
||
```
|
||
|
||
任意:
|
||
|
||
```powershell
|
||
$env:OPENAI_MODEL = "..."
|
||
$env:OPENAI_REASONING_EFFORT = "low"
|
||
$env:MT5_EA_FILE_PREFIX = "HIT_GOLD_10001"
|
||
$env:MT5_PRICE_DIGITS = "2"
|
||
```
|
||
|
||
`OPENAI_MODEL` 未設定時は `src/ea_py/constants.py` の `DEFAULT_GPT_MODEL` を使います。`OPENAI_REASONING_EFFORT` は `none`, `low`, `medium`, `high`, `xhigh` のいずれかです。`MT5_EA_FILE_PREFIX` と `MT5_PRICE_DIGITS` は手動実行時だけ指定すればよく、EA/bat経由では自動設定されます。
|
||
|
||
## 主なモジュール
|
||
|
||
```text
|
||
src/ea_py/config.py 環境変数から実行時設定を読み込む
|
||
src/ea_py/constants.py 共通定数
|
||
src/ea_py/paths.py MT5 連携ファイルパス
|
||
src/ea_py/io/ohlc_csv.py OHLC CSV 読み込みと検証
|
||
src/ea_py/io/mt5_files.py 結果ファイルと done ファイルの書き込み
|
||
src/ea_py/charting/candlestick.py ローソク足 PNG 生成
|
||
src/ea_py/market/volatility.py True Range / EATR / 数値要約
|
||
src/ea_py/market/trend_state.py H4 方向判定と market_state 合成
|
||
src/ea_py/market/target_prices.py GPT 出力のパースと価格検証
|
||
src/ea_py/market/target_zones.py 分割エントリー用ゾーン出力
|
||
src/ea_py/market/imbalance.py H1 インバランス初動判定
|
||
src/ea_py/openai_client.py OpenAI Responses API ラッパー
|
||
src/ea_py/pipelines/ H4/H1 パイプライン
|
||
```
|
||
|
||
詳細なフォルダ構成は `docs/architecture/folder-structure.md` も参照してください。
|
||
|
||
## 開発
|
||
|
||
Python 3.13 と `uv` を前提にします。
|
||
|
||
```powershell
|
||
uv sync
|
||
```
|
||
|
||
個別実行:
|
||
|
||
```powershell
|
||
uv run python get_trend_reply.py
|
||
uv run python get_entry_reply.py
|
||
```
|
||
|
||
品質チェック:
|
||
|
||
```powershell
|
||
uv run python -m py_compile get_trend_reply.py get_entry_reply.py
|
||
uv run ruff check .
|
||
uv run ty check
|
||
uv run pytest
|
||
```
|
||
|
||
## 注意
|
||
|
||
- API キーや接続情報はコードへ直書きしないでください。
|
||
- `work/` 配下は作業用・参照用であり、実行時の正本ではありません。
|
||
- Python は候補価格を作るだけで、注文送信、ポジション操作、未約定注文キャンセルは行いません。
|
||
- 出力仕様を変える場合は、MQL5 EA 側の読み込み処理も同時に確認してください。
|