CLAUDE.md

1# Saira-Trading
2 
3نظام تداول شبه-آلي (swing trading) لأسهم أمريكية، مبني على تحليل فني/كمّي/فلكي
4مستقل بايثون (بدون أي اعتماد على Timing Solution)، ضمن فلاتر أخلاقية صارمة.
5القرار النهائي دايمًا مراجعة يدوية — لا يوجد تنفيذ آلي لأي أمر شراء/بيع حقيقي.
6 
7## تفضيل تواصل ثابت
8 
9- **كلّم عبده بالعربي دايمًا** (طلب صريح 2026-07-25) — مش بس في الشرح، في كل
10  رد نصي أثناء العمل على المشروع ده، بغض النظر عن الجلسة أو الجهاز (سواء
11  الجلسة السحابية أو جهاز عبده المحلي "Mahdy").
12 
13## قواعد ثابتة (لا تتغير بدون نقاش صريح)
14 
15- **Timing Solution (TS) اتشال من المشروع بالكامل (قرار 2026-07).** كان
16  المشروع أصلاً مبني على دمج إشارات TS الدورية/الفلكية مع تحليل فني مستقل، لكن
17  بعد قياس دقة TS التاريخية (verify_signals.py) وطلوعها ~19.7% فقط — ضعيفة جدًا
18  ومكلفة (شبكة + وقت) من غير عائد حقيقي — تقرر شيلها نهائيًا. الملفات
19  `extract_signals.py` / `verify_signals.py` / `confirm_signals.py` /
20  `independent_signals.py` اتنقلت لمجلد `deprecated_ts/` (مش محذوفة، للمرجعية
21  بس — ما تستوردش منها في كود جديد). `committee_signals.py` بقى مكتبة تصويت
22  مشتركة فقط (بدون main() خاص بيه)، و`full_universe_analysis.py` هو الـ
23  pipeline الوحيد الشغّال دلوقتي — بيغطي كامل NASDAQ+NYSE مع الفلتر الأخلاقي
24  مطبّق، بدون أي اعتماد على TS من الأساس.
25- **دقة TS التاريخية (~19.7%، كانت في verify_signals.py) ما تتستخدمش أبدًا في
26  تحجيم الصفقات أو أي قرار risk management** — نفس السبب اللي خلّى TS تتشال
27  خالص. لو أي كود جديد بيستورد من `deprecated_ts/` داخل سياق تحجيم المخاطر أو
28  اختيار المرشحين، ده خطأ ولازم يتراجع.
29- **الفلتر الأخلاقي (`ethical_screen.py`) إلزامي على أي تحليل لسهم جديد**:
30  استبعاد بنوك، دفاع/أسلحة، وقائمة BDS المحددة يدويًا (`BDS_EXCLUDED_TICKERS`).
31  مبني على sector/industry من yfinance + قائمة تيكرات ثابتة، مش سكان تلقائي.
32- **سقف صلب على قيمة أي صفقة مقترحة**: `MAX_ORDER_VALUE_USD` في
33  `suggest_execution.py`. أي كود تحجيم جديد (زي `risk_management.py`) لازم
34  يستورد الثابت ده مش يكرره برقم مختلف، ودايمًا يحجّم لأسفل منه فقط.
35- كل سكريبت بينتج مخرجات بيحتفظ بنسخة أرشيفية (`runs/archive/`) بالإضافة
36  للنسخة الأحدث — القرار ده متعمد (بيانات تدريب مستقبلية محتملة)، متشيلوش.
37- **أي backtesting (`backtest.py` وأي سكريبت مقارنة زيه) لازم يقرأ بيانات
38  الأسعار من الداتا المحلية على الجهاز، مش من yfinance مطلقًا**:
39  `D:\EGX.Daily.2000-2023\data\daily\data\daily\us`
40  (= `full_universe_analysis.LOCAL_MARKET_DATA_DIR`، عبر
41  `build_local_ticker_index()`/`load_local_history()`). ده شغّال على جهاز
42  Abdo بس (زي `refresh_ticker_universe.py` بالظبط) ومش جزء من الأتمتة السحابية
43  — بيشيل مشكلة الشبكة/rate-limit اللي كانت بتخلي backtest على مئات الأسهم
44  ياخد وقت طويل جدًا، فالـ backtest دلوقتي المفروض يتعمل على 400 سهم على
45  الأقل، ويفضّل لغاية 1000 سهم لو الوقت يسمح (`TICKER_SAMPLE_SIZE` في
46  backtest.py). **تنبيه:** فيه نسخة قديمة (stale) من نفس الداتا على
47  `D:\EGX.Daily.2000-2023\data\daily\us` (من غير تكرار `data\daily`) بتوقف
48  عند 2026-04-02 بدل التحديث الفعلي — لازم يتتأكد إن آخر تاريخ في الداتا
49  المستخدمة قريب من تاريخ النهاردة قبل أي backtest جديد.
50- **مؤشر اتجاه جان الميكانيكي (2-bar swing-high breakout / swing-low stop)
51  اتختبر ورفض (2026-07-13، `src/gann_swing_strategy_backtest.py`)**: على
52  400 سهم × 6 شهور، معدل الإصابة الحقيقي (بعد احتساب "missed" كخسارة —
53  نفس معيار `evaluate_forward_outcome`) كان 13.1%، أقل من اللجنة الحالية
54  (42.8%) وأقل من المعدل الأساسي البسيط (25.3%). **لا يُستخدم كصوت خامس في
55  اللجنة بشكله الحالي.** السبب: قاعدة الدخول وحدها (بلا حجم هدف/وقف مبني
56  على دعم/مقاومة حقيقي) بتسيب 79% من الإشارات تتوه جانبيًا بلا خروج خلال
57  نافذة الاختبار. الكود والـ harness موجودين لإعادة اختبار نسخة محسّنة
58  لاحقًا (فلتر ADX، حجم هدف مختلف) من غير إعادة بناء من الصفر.
59 
60## Pipeline (الترتيب مهم)
61 
62```
63full_universe_analysis.py -> runs/full_universe_results.csv (السكان الرئيسي: كامل NASDAQ+NYSE، فلتر أخلاقي، تصويت 4 مجموعات، دخول/خروج)
64                           -> runs/committee_candidates.csv (نفس الخطوة: شورت ليست متنوعة قطاعيًا، top 3)
65build_report.py           -> runs/report.html             (داشبورد HTML تفاعلي من full_universe_results.csv)
66format_report.py          -> runs/committee_report.md      (تقرير Markdown من committee_candidates.csv، لمشاركته مع Claude)
67suggest_execution.py      -> runs/execution_suggestions.csv (اقتراح حجم صفقة من full_universe_results.csv، مراجعة يدوية فقط)
68```
69 
70(الملفات القديمة `extract_signals.py`/`verify_signals.py`/`confirm_signals.py`/
71`independent_signals.py` كانت phases 1-4 من TS pipeline قديم — اتشالت بالكامل،
72موجودة في `deprecated_ts/` للمرجعية بس، مش جزء من الـ pipeline الحالي.)
73 
74كل سكريبت من دول عنده docstring مفصّل في أوله بيشرح المدخلات/المخرجات
75والافتراضات — اقرأه قبل التعديل بدل تخمين البنية.
76 
77## بنية committee_signals.py (أهم ملف في المشروع)
78 
794 مجموعات تصويت مستقلة، كل واحدة بترجع GroupResult (buy/sell/neutral/unavailable):
80- **Technical**: MACD, Golden/Death Cross, Bollinger Bands, ADX-gated trend
81- **Quantitative**: Analyst consensus, unusual volume
82- **Astrological**: Gann Square of Nine (معايرة لكل سهم عبر
83  `gann_decision_system.gann_committee_vote` — مش `gann_square9.py` القديم
84  التقريبي)
85- **Advanced Technical**: TA-Lib snapshot + Ichimoku + Pivot Points + Volume Profile
86  (`advanced_technical_tools.py`)
87 
88الترشيح النهائي (`select_diversified_candidates`): `total_buy_votes >
89total_sell_votes`، مفيش حد أدنى للأصوات، مع تنويع القطاعات
90(`MAX_CANDIDATES_PER_SECTOR`).
91 
92## أدوات Gann (Layers 1-4)
93 
94- Layer 1 (رياضي/هندسي): `gann_square9_precise.py` (الطريقة الدقيقة، overlay
95  method) + `gann_layer1_tools.py` (Gann Angles, Hexagon, Circle Chart).
96  **لا تستخدم `gann_square9.py` القديم** (تقريب sqrt+offset) في أي كود جديد —
97  موجود للمرجعية بس.
98- Layer 2 (زمني): `gann_time_cycles.py` — تنبؤ تواريخ عبر cell/angle، تحقق ضد
99  مثال ALTR في الكتاب.
100- Layer 3 (فلكي): `gann_astrology.py` (مواقع كواكب حقيقية via ephem، مش تقريب)
101  + `gann_planetary_lines.py` (خطوط سعرية مستمرة تتابع حركة كوكب حقيقية).
102- Layer 4 (قرار): `gann_decision_system.py` — يعاير الزاوية/الخط الأنسب لكل
103  سهم بدل افتراض زاوية ثابتة (فلسفة "test then trust").
104- `gann_increment_selection.py`: يحدد الزيادة السعرية المناسبة (increment)
105  حسب ATR الفعلي للسهم، مش رقم ثابت.
106 
107## أدوات مساعدة
108 
109- `yf_retry.call_with_retry()`: أي نداء yfinance جديد لازم يمر من هنا —
110  Yahoo بيعمل rate-limit بسرعة تحت التزامن (خبرة موثقة، 8 workers فشلت،
111  3 workers + retry نجحت).
112- الفلتر الأخلاقي عبر `ethical_screen.screen_ticker()` قبل أي تحليل سعري.
113 
114## أوامر شائعة
115 
116```bash
117python src/full_universe_analysis.py     # بطيء — كامل NASDAQ+NYSE، تلاجي عشرات الدقايق
118python src/build_report.py
119python src/format_report.py
120python src/suggest_execution.py
121pip install pandas numpy yfinance openpyxl --user   # لا يوجد requirements.txt موحّد بعد
122```
123 
124أو `run_daily.ps1` (يشغّل full_universe_analysis.py ثم build_report.py بالترتيب
125ويؤرشف نسخة) — `register_scheduled_task.ps1` يجدولها يوميًا عبر Windows Task
126Scheduler.
127 
128بيئة العمل: Windows، Python 3.14.6، المشروع في `C:\Users\Mahdy\Saira-Trading\`.
129 
130## أسلوب الكود المتوقع (من الكود الموجود)
131 
132- كل دالة رئيسية بترجع dataclass واضح (`GroupResult`, `VerificationResult`,
133  إلخ) مش dict خام — القيم القابلة للقراءة في التقرير أهم من الاختصار.
134- لا تخمين صامت: بيانات ناقصة = `None`/`"unavailable"` صريح، مش قيمة افتراضية
135  مموّهة (مبدأ متكرر في كل الملفات: "fail loud, don't let NaN silently mean
136  something").
137- أي threshold/ثابت رقمي (VOLUME_SPIKE_THRESHOLD، ADX_TREND_THRESHOLD، إلخ)
138  بيتكتب كـ constant معلّق في أول الملف مع تعليق يوضح إنه "نقطة بداية معقولة"
139  مش قيمة نهائية مثبتة.
140- توثيق provenance: أي معادلة Gann لازم تتحقق ضد مثال حقيقي من الكتب
141  المرجعية (موجودة في project knowledge) قبل ما تتوثق كـ "صحيحة".
142 
143## ما لا يجب فعله
144 
145- ما تحطش أي كود تنفيذ آلي حقيقي لأمر شراء/بيع — المشروع كله "اقتراح للمراجعة
146  اليدوية" فقط (preflight-checklist.md لازم تتراجع قبل أي تنفيذ حقيقي).
147- ما ترجّعش TS أو تستورد من `deprecated_ts/` في كود جديد (اتفق عليه صراحةً —
148  راجع أعلى) — لو محتاج سياق تاريخي عن ليه اتشال، الملفات نفسها لسه موجودة هناك.
149- ما ترفعش MAX_ORDER_VALUE_USD أو أي سقف أمان من غير تغيير صريح ومرئي في
150  `suggest_execution.py` نفسه.
151