gavindiaz/EA_with_Python
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Consolidate Python ignore rules into root gitignore

Browse Source
This commit is contained in:
Hiroaki86
2026-05-27 23:01:28 +09:00
commit fa3394415d
399 changed files with 509103 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python_for_ea/docs/architecture/folder-structure.md
+229
View File
@@ -0,0 +1,229 @@
# Folder Structure
## 目的
このドキュメントは、`C:\ea_py` のフォルダ構成に関する正本である。
現在のプロジェクトは、MT5 HIT-EAから出力されたOHLC CSVをPythonで解析し、OpenAI APIを使ってGOLD/XAUUSD向けの相場環境とエントリー候補価格を返す補助アプリケーションである。
MT5 EAから `bat/` 経由でルート直下のPythonスクリプトが呼ばれているため、現時点ではルート直下の `get_trend_reply.py` と `get_entry_reply.py` を実行入口として維持する。
## 現在のフォルダ構成
```text
C:/ea_py/
├─ AGENTS.md
├─ README.md
├─ pyproject.toml
├─ uv.lock
├─ get_trend_reply.py
├─ get_entry_reply.py
├─ src/
│ └─ ea_py/
│ ├─ __init__.py
│ ├─ config.py
│ ├─ constants.py
│ ├─ paths.py
│ ├─ types.py
│ ├─ io/
│ │ ├─ __init__.py
│ │ ├─ debug_logs.py
│ │ ├─ mt5_files.py
│ │ └─ ohlc_csv.py
│ ├─ charting/
│ │ ├─ __init__.py
│ │ └─ candlestick.py
│ ├─ market/
│ │ ├─ __init__.py
│ │ ├─ volatility.py
│ │ ├─ trend_state.py
│ │ └─ target_prices.py
│ ├─ prompts/
│ │ ├─ __init__.py
│ │ ├─ trend_prompt.py
│ │ └─ entry_prompt.py
│ ├─ openai_client.py
│ └─ pipelines/
│ ├─ __init__.py
│ ├─ trend_pipeline.py
│ └─ entry_pipeline.py
├─ tests/
│ └─ unit/
│ ├─ test_trend_state.py
│ ├─ test_target_prices.py
│ └─ test_volatility.py
├─ bat/
│ ├─ get_trend_reply.bat
│ └─ get_entry_reply.bat
├─ docs/
│ ├─ architecture/
│ │ └─ folder-structure.md
│ └─ refactor/
│ └─ gold_strategy_20260503.md
└─ work/
├─ get_trend_reply.py
└─ get_entry_reply.py
```
## 現在の各ファイル・フォルダの責務
| パス | 責務 |
|---|---|
| `AGENTS.md` | AIエージェント向けの共通作業方針。 |
| `pyproject.toml` | Pythonバージョン、依存関係、開発ツール定義。 |
| `uv.lock` | `uv` による依存関係ロックファイル。 |
| `get_trend_reply.py` | H4判定パイプラインを呼び出すMT5/bat互換用の薄い実行入口。 |
| `get_entry_reply.py` | H1候補生成パイプラインを呼び出すMT5/bat互換用の薄い実行入口。 |
| `src/ea_py/` | Python補助アプリケーションの正本コード。設定、I/O、チャート生成、相場計算、プロンプト、OpenAI呼び出し、パイプラインを分離して置く。 |
| `tests/unit/` | 外部APIやMT5 I/Oに依存しない純粋ロジックのUnit Test。 |
| `bat/get_trend_reply.bat` | MT5 EAから `get_trend_reply.py` を起動するためのバッチファイル。 |
| `bat/get_entry_reply.bat` | MT5 EAから `get_entry_reply.py` を起動するためのバッチファイル。 |
| `docs/architecture/` | 構成、責務、設計方針の正本を置く。 |
| `docs/refactor/` | 戦略改善案、リファクタリングメモ、検討資料を置く。 |
| `work/` | 作業用・参照用の一時ファイル置き場。実行時の正本として扱わない。 |
## 外部連携ファイル
MT5側の `MQL5\Files` 配下に、Pythonとの連携ファイルが置かれる。
代表例:
```text
C:/Users/new/AppData/Roaming/MetaQuotes/Terminal/{terminal_ID}/MQL5/Files/
├─ ohlc_H4.csv
├─ ohlc_H1.csv
├─ trend_state.txt
├─ target_prices.txt
├─ process_done_trend.txt
├─ process_done_entry.txt
├─ process_running_trend.txt
├─ process_running_entry.txt
├─ debug_trend.txt
├─ debug_entry.txt
├─ tmp_chart_trend.png
├─ tmp_chart_short.png
└─ tmp_chart_long.png
```
これらは実行時生成物であり、原則として `C:\ea_py` 配下へコピーして正本化しない。
## MQL5 EAファイル
MQL5 EAファイルは、MT5データフォルダ配下に存在する。
例:
```text
C:/Users/new/AppData/Roaming/MetaQuotes/Terminal/{terminal_ID}/MQL5/Experts/MyProject/
└─ HIT-EA_refactor_ver3.mq5
```
EAファイルはこのPythonプロジェクトの外部連携先として扱う。Python側の出力形式を変更する場合は、EA側の読込処理も同時に確認する。
## 推奨フォルダ構成
現在は、以下の構成へ移行済みである。今後は必要に応じて、設定ファイルやIntegration Testを追加する。
ルート直下の `get_trend_reply.py` と `get_entry_reply.py` は、MT5/bat互換のため薄いエントリーポイントとして残す。
```text
C:/ea_py/
├─ AGENTS.md
├─ README.md
├─ pyproject.toml
├─ uv.lock
├─ get_trend_reply.py
├─ get_entry_reply.py
├─ bat/
│ ├─ get_trend_reply.bat
│ └─ get_entry_reply.bat
├─ src/
│ └─ ea_py/
│ ├─ __init__.py
│ ├─ config.py
│ ├─ paths.py
│ ├─ constants.py
│ ├─ types.py
│ ├─ io/
│ │ ├─ __init__.py
│ │ ├─ debug_logs.py
│ │ ├─ mt5_files.py
│ │ └─ ohlc_csv.py
│ ├─ charting/
│ │ ├─ __init__.py
│ │ └─ candlestick.py
│ ├─ market/
│ │ ├─ __init__.py
│ │ ├─ volatility.py
│ │ ├─ trend_state.py
│ │ └─ target_prices.py
│ ├─ prompts/
│ │ ├─ __init__.py
│ │ ├─ trend_prompt.py
│ │ └─ entry_prompt.py
│ ├─ openai_client.py
│ └─ pipelines/
│ ├─ __init__.py
│ ├─ trend_pipeline.py
│ └─ entry_pipeline.py
├─ tests/
│ └─ unit/
│ ├─ test_trend_state.py
│ ├─ test_target_prices.py
│ └─ test_volatility.py
└─ docs/
├─ architecture/
│ └─ folder-structure.md
└─ refactor/
└─ gold_strategy_20260503.md
```
## 推奨モジュール責務
| モジュール | 責務 |
|---|---|
| `src/ea_py/config.py` | 環境変数、モデル名、デバッグ設定などの設定読み込み。 |
| `src/ea_py/paths.py` | MT5データフォルダ、入力CSV、出力ファイルパスの組み立て。 |
| `src/ea_py/constants.py` | `market_state`、ATR期間、出力サイズなどの定数。 |
| `src/ea_py/types.py` | OHLCバー、OHLC要約、13行出力などの型定義。 |
| `src/ea_py/io/mt5_files.py` | doneファイル、runningファイル、atomic writeなどMT5連携I/O。 |
| `src/ea_py/io/ohlc_csv.py` | OHLC CSVの読込、型変換、バリデーション。 |
| `src/ea_py/io/debug_logs.py` | デバッグ理由ログの追記処理。 |
| `src/ea_py/charting/candlestick.py` | ローソク足PNG生成。 |
| `src/ea_py/market/volatility.py` | True Range、Exponential ATR、ボラティリティ分類。 |
| `src/ea_py/market/trend_state.py` | H4方向判定結果とボラティリティ分類の合成。 |
| `src/ea_py/market/target_prices.py` | GPT出力のパース、価格整合性チェック、13行形式への変換。 |
| `src/ea_py/prompts/trend_prompt.py` | H4相場環境判定プロンプトの生成。 |
| `src/ea_py/prompts/entry_prompt.py` | H1候補価格生成プロンプトの生成。 |
| `src/ea_py/openai_client.py` | OpenAI API呼び出しの薄いラッパー。 |
| `src/ea_py/pipelines/trend_pipeline.py` | H4判定処理全体のオーケストレーション。 |
| `src/ea_py/pipelines/entry_pipeline.py` | H1候補生成処理全体のオーケストレーション。 |
## 移行ルール
- まずは既存のルート直下スクリプトの実行契約を壊さない。
- 共通化する処理から `src/ea_py/` へ移し、ルート直下スクリプトは `main()` を呼ぶだけの薄い入口へ近づける。
- 1回の変更で、ファイル移動、ロジック変更、戦略変更を同時に大きく混ぜない。
- ファイル移動を行う場合は、`bat/`、import、テスト、ドキュメントを同時に更新する。
- `work/` 配下のファイルを実装の正本として参照しない。必要な差分だけを確認し、正本へ取り込む。
- FastAPI、Streamlit、SQL Server、OracleDBなどのフォルダは、実際にその機能を追加するまで作らない。
## テスト配置方針
- Unit Testは `tests/unit/` に置く。
- Integration Testは `tests/integration/` に置き、`@pytest.mark.integration` を付ける。
- OpenAI API、MT5ファイルI/O、現在時刻はUnit Testではmockする。
- 重要なテスト対象:
- `market_state` の分類
- ATR/ボラティリティ計算
- GPT出力パース
- `target_prices.txt` の13行契約
- ファイル書込順序とdoneファイル作成順序
- 異常時に安全側へ倒す処理
## 生成物・一時ファイル
- `__pycache__/`、`.pytest_cache/`、チャートPNG、MT5連携のdone/runningファイルは生成物として扱う。
- 生成物を設計上の正本にしない。
- デバッグログは原因調査に使うが、恒久的な仕様はドキュメントへ反映する。
python_for_ea/docs/refactor/gold_strategy_20260503.md
+347
View File
@@ -0,0 +1,347 @@
# HIT-EA ゴールド向け戦略追加アイデア整理
## 目的
HIT-EA系の戦略に対して、ゴールド（XAUUSD）のようにボラティリティが大きい銘柄向けに追加できそうなアイデアを整理する。
本ファイルでは、以下の4項目に絞って記載する。
- ボラティリティ分類の導入
- 異常ボラティリティ時は停止する
- レンジ逆張りを厳しくする
- 高ボラトレンドでは逆張りを禁止する
現時点では、各提案内容の採用・不採用は判断しない。
後で検証・バックテスト・実装難易度を確認しながら、必要不要を判断する前提とする。
---
# 1. ボラティリティ分類の導入
## 1.1 概要
ゴールドは、通常のFX通貨ペアよりもボラティリティが大きく、同じ「上昇」「下降」「レンジ」でも値動きの強さによって有効な戦略が変わる。
そのため、H4の環境認識に対して、トレンド方向だけでなくボラティリティの高低を組み合わせた分類を導入する。
通常の分類例は以下のようになる。
```text
0 = レンジ
1 = 上昇トレンド
2 = 下降トレンド
```
ゴールド向けには、以下のように分類を拡張する。
```text
0 = 低ボラレンジ
1 = 高ボラレンジ
2 = 低ボラ上昇
3 = 高ボラ上昇
4 = 低ボラ下降
5 = 高ボラ下降
6 = 異常ボラ
```
## 1.2 判定の考え方
ボラティリティ分類では、以下のような情報を使って判定する。
```text
H4_ATR
H1_ATR
過去N本のATR平均
直近ローソク足の値幅
直近ローソク足のヒゲの長さ
スプレッド
```
例として、現在のATRが過去平均より明らかに大きい場合は「高ボラ」、さらに異常に大きい場合は「異常ボラ」と判定する。
```text
current_atr <= atr_ma * 1.2 → 通常ボラ
current_atr > atr_ma * 1.2 → 高ボラ
current_atr > atr_ma * 2.0 → 異常ボラ
```
倍率は仮の値であり、バックテストで調整する前提とする。
## 1.3 戦略選択例
| 環境 | 戦略の考え方 |
|---|---|
| 低ボラレンジ | 取引しない、または小さめのレンジ逆張り |
| 高ボラレンジ | レンジ端からの逆張り。ただし条件を厳しくする |
| 低ボラ上昇 | 押し目買い中心 |
| 高ボラ上昇 | ブレイク買い、浅い押し目買い中心 |
| 低ボラ下降 | 戻り売り中心 |
| 高ボラ下降 | ブレイク売り、浅い戻り売り中心 |
| 異常ボラ | 新規注文停止 |
## 1.4 期待できる効果
トレンド方向だけでなく、値動きの強さに応じて戦略を切り替えられる。
特にゴールドでは、通常ボラと高ボラで値動きの性質が大きく変わるため、同じ上昇トレンドでも以下のように戦略を分けやすくなる。
```text
低ボラ上昇 → 押し目買い中心
高ボラ上昇 → ブレイク買い、浅い押し目買い中心
```
また、異常ボラを明確に分類することで、無理に取引しない判断を入れやすくなる。
---
# 2. 異常ボラティリティ時は停止する
## 2.1 概要
ゴールドは、経済指標、要人発言、地政学リスク、金利関連ニュースなどで急変しやすい。
急変時に通常ロジックで新規注文を出すと、スリッページ、急反転、スプレッド拡大に巻き込まれる可能性がある。
そのため、異常ボラティリティを検知した場合は、新規注文を停止する条件を追加する。
## 2.2 停止条件例
以下のような条件を組み合わせて、異常ボラティリティを判定する。
```text
H1_ATR > 過去20本ATR平均 × 2.0
直近1本の値幅 > ATR × 2.5
現在スプレッド > 通常時の2倍
直近ローソク足のヒゲが極端に長い
短時間で大きく一方向に動いている
```
## 2.3 判定例
```text
if current_atr > atr_ma * 2.0:
新規注文停止
```
または、複数条件を使って停止判定を行う。
```text
異常ボラ判定 = false
if current_atr > atr_ma * 2.0:
異常ボラ判定 = true
if latest_candle_range > current_atr * 2.5:
異常ボラ判定 = true
if current_spread > average_spread * 2.0:
異常ボラ判定 = true
if 異常ボラ判定:
新規注文停止
```
## 2.4 停止時の処理方針
異常ボラティリティ時は、新規注文だけを停止し、既存ポジションは別ロジックで管理する。
```text
新規注文は出さない
未約定注文はキャンセル候補にする
既存ポジションは管理を継続する
追加エントリーは禁止する
必要に応じてSLを建値へ移動する
```
## 2.5 注意点
異常ボラ停止の条件を厳しくしすぎると、ゴールドがよく動く時間帯のチャンスを逃す可能性がある。
逆に条件を緩くしすぎると、急変相場で停止できない可能性がある。
そのため、最初はログ出力を行い、実際の相場で以下を確認してから閾値を調整する。
```text
通常時のATR
高ボラ時のATR
急変時のATR
通常時のスプレッド
急変時のスプレッド
直近足の平均的な値幅
```
## 2.6 期待できる効果
急騰急落の途中で無理にエントリーすることを防げる。
ゴールドでは特に重要度が高いリスク回避機能である。
---
# 3. レンジ逆張りを厳しくする
## 3.1 概要
ゴールドのレンジは振れ幅が大きく、一見レンジに見えてもそのままブレイクすることがある。
そのため、単純に以下のような判断だけで逆張りするのは危険である。
```text
レンジ上限だから売り
レンジ下限だから買い
```
ゴールド向けには、レンジ端に到達したことに加えて、反転の根拠やブレイク回避条件を追加する。
## 3.2 買い逆張り条件例
```text
H4 = レンジ
価格がレンジ下限付近
H1で下ヒゲが出た
直近安値を大きく割っていない
SLまでの距離がATR基準内
直近足の値幅が異常に大きくない
ブレイク直後ではない
```
## 3.3 売り逆張り条件例
```text
H4 = レンジ
価格がレンジ上限付近
H1で上ヒゲが出た
直近高値を大きく超えていない
SLまでの距離がATR基準内
直近足の値幅が異常に大きくない
ブレイク直後ではない
```
## 3.4 見送り条件例
レンジ内であっても、以下のような場合は逆張りを見送る。
```text
価格がレンジ中央付近にある
レンジ上限・下限まで十分近くない
直近足の値幅が大きすぎる
上限・下限を強くブレイクした直後
スプレッドが広い
異常ボラティリティ判定中
H4の環境がトレンドへ変化し始めている
```
## 3.5 戦略選択例
| H4環境 | 逆張り方針 |
|---|---|
| 低ボラレンジ | 条件を満たす場合のみ逆張り候補 |
| 高ボラレンジ | レンジ端のみ逆張り候補。ただし条件をより厳しくする |
| 高ボラ上昇 | 売り逆張りは禁止 |
| 高ボラ下降 | 買い逆張りは禁止 |
| 異常ボラ | 新規注文停止 |
## 3.6 期待できる効果
レンジブレイクに巻き込まれる逆張りを減らせる。
単純なレンジ上限・下限だけで判断するより、ゴールド特有の大きな振れに対応しやすくなる。
---
# 4. 高ボラトレンドでは逆張りを禁止する
## 4.1 概要
ゴールドで強いトレンドが出ている場合、逆張りは大きな損失につながりやすい。
特に高ボラティリティを伴う上昇トレンドや下降トレンドでは、一方向に大きく伸びることがある。
そのため、高ボラトレンド中はトレンドに逆らう注文を禁止する。
## 4.2 基本方針
高ボラ上昇では、売り逆張りを禁止する。
```text
H4 = 高ボラ上昇
→ 逆張り売りは禁止
→ ブレイク買い、浅い押し目買いのみ許可
```
高ボラ下降では、買い逆張りを禁止する。
```text
H4 = 高ボラ下降
→ 逆張り買いは禁止
→ ブレイク売り、浅い戻り売りのみ許可
```
## 4.3 条件例
高ボラ上昇トレンドの判定例。
```text
H4 = 上昇
H4_ATRが平均以上
H1の短期MAが上向き
H1終値が短期MAより上
直近高値を更新している
```
高ボラ下降トレンドの判定例。
```text
H4 = 下降
H4_ATRが平均以上
H1の短期MAが下向き
H1終値が短期MAより下
直近安値を更新している
```
## 4.4 許可する戦略例
| H4環境 | 許可する戦略 |
|---|---|
| 高ボラ上昇 | ブレイク買い、浅い押し目買い |
| 高ボラ下降 | ブレイク売り、浅い戻り売り |
| 高ボラレンジ | レンジ端のみ逆張り |
| 異常ボラ | 新規停止 |
## 4.5 禁止する戦略例
| H4環境 | 禁止する戦略 |
|---|---|
| 高ボラ上昇 | 逆張り売り |
| 高ボラ下降 | 逆張り買い |
| 異常ボラ | すべての新規注文 |
## 4.6 期待できる効果
強いトレンド中の危険な逆張りを減らせる。
ゴールドでは一方向に大きく伸びる局面があるため、逆方向の注文を制限することで大きな損失を避けやすくなる。
---
# 5. 全体方針
HIT-EAの基本構造は維持する。
```text
H4で環境認識
H1で候補作成
1時間以内に約定しなければキャンセル
環境に合わない戦略は出さない
```
ゴールド向けには、以下の4点を中心に検討する。
```text
ボラティリティ分類を導入する
異常ボラでは新規注文を停止する
レンジ逆張り条件を厳しくする
高ボラトレンド中の逆張りを禁止する
```
この方針により、ゴールド特有の大きな値動きに対して、攻める場面と止める場面を分けやすくする。