== Component: setup_quality_detection.py ==
=== Purpose (Trading Context) ===
The Grader - This component answers: "How good is this trading setup?"
Think of it like a teacher grading an exam: Each setup is scored on 5 factors, penalties are applied for bad conditions, and a final grade (A+ to F) is assigned. The grade determines position size and whether we should trade at all.
Key Philosophy: Not all setups are equal. A+ setups get bigger positions. C/D/F setups are rejected by signal generation.
=== What It Does (Simple Terms) ===
1. Receives analyzed data from upstream components
2. Scores each setup on 5 weighted factors (0-100 each)
3. Applies penalties for adverse market conditions (creeper, MA struggle, etc.)
4. Caps score if A+ criteria not met
5. Assigns letter grade (A+ to F)
6. Recommends position size based on grade
=== Inputs ===
| Input |
Source |
What It Provides
|
| timeframe_analysis |
multi_timeframe_analysis.py |
Alignment score, aligned flag
|
| market_state |
market_state_analysis.py |
Creeper move, MA struggle, railroad trend, trend phase, institutional fight
|
| entry_data |
Calculated in main.py |
near_key_level, near_ma, clean_entry, risk_reward
|
| strategy_config |
Configuration |
Strategy ID
|
| timestamp |
Current bar |
Timestamp for logging
|
=== Outputs (SetupQualityResult) ===
| Field |
Type |
Description
|
| grade |
SetupQualityGrade |
A+, A, B, C, D, or F
|
| score |
float |
0-100 final score after all penalties
|
| factor_scores |
Dict |
Individual scores for each of 5 factors
|
| position_size |
int |
Recommended lots (1 or 2)
|
| risk_percent |
float |
Risk % based on grade
|
| can_auto_trade |
bool |
Only A+ and A are auto-tradeable
|
=== The 5-Factor Scoring System ===
Total Weight = 100% (must sum to exactly 1.0)
| Factor |
Weight |
What It Measures |
Calculation
|
| Timeframe Alignment |
30% |
Are all timeframes pointing same direction? |
alignment_score × 100
|
| Trend Strength |
20% |
Is trend healthy? |
100 - penalties + bonuses
|
| Entry Quality |
15% |
Is entry at a good spot? |
100 + bonuses - penalties
|
| Key Level Proximity |
20% |
Is price near important level? |
100 - 50 if not near key level
|
| Risk/Reward |
15% |
Is R:R acceptable? |
Lookup table (see below)
|
=== Risk/Reward Scoring Table ===
EXACT boundaries from specification:
| R:R Range |
Score |
Rating
|
| < 1.0 |
0 |
Unacceptable
|
| [1.0, 1.5) |
40 |
Poor
|
| [1.5, 2.0) |
70 |
Acceptable
|
| [2.0, 3.0) |
90 |
Good
|
| >= 3.0 |
100 |
Excellent
|
=== Penalties & Bonuses (Trend Strength Factor) ===
Applied to Factor 2: Trend Strength
| Condition |
Adjustment |
Trigger Field
|
| Creeper Move |
-50 |
is_creeper_move = True
|
| MA Struggle |
-30 |
price_ma_struggle = True
|
| No Two-Day Trend |
-30 |
has_two_day_trend = False
|
| Not Middle Phase |
-25 |
trend_phase ≠ MIDDLE
|
| Railroad Trend |
+15 |
is_railroad_trend = True
|
=== Penalties & Bonuses (Entry Quality Factor) ===
Applied to Factor 3: Entry Quality
| Condition |
Adjustment |
Trigger
|
| Near Key Level |
+10 |
entry_data['near_key_level'] = True
|
| Not Near MA |
-40 |
entry_data['near_ma'] = False
|
| Clean Entry |
+10 |
entry_data['clean_entry'] = True
|
=== Institutional Fight Penalty (Algorithm 4) ===
Philosophy: When institutions are battling each other, don't trade.
* Trigger: institutional_fight_in_progress = True
* Effect: Score × 0.7 (30% haircut)
* Applied AFTER weighted score calculation
=== A+ Criteria Enforcement (Algorithm 5) ===
Philosophy: A+ is earned, not given. Must meet ALL criteria.
To qualify for A+ (score >= 90):
1. All timeframes aligned (timeframe_analysis.aligned = True)
2. Entry near MA (entry_data['near_ma'] = True)
3. Has two-day trend (market_state.has_two_day_trend = True)
If ANY criterion fails: Score capped at 79 (forced to B grade)
=== Grade Thresholds (Algorithm 6) ===
| Grade |
Min Score |
Position Size |
Risk % |
Auto-Trade?
|
| A+ |
90 |
2 lots |
1.5% |
Yes
|
| A |
80 |
1 lot |
1.2% |
Yes
|
| B |
70 |
1 lot |
1.0% |
No
|
| C |
60 |
1 lot |
0.8% |
No
|
| D |
50 |
1 lot |
0.5% |
No
|
| F |
<50 |
1 lot |
0.3% |
No
|
Note: C/D/F grades are REJECTED by signal_generation (no trade taken).
=== Key Methods (For Developers) ===
| Method |
Purpose |
Critical Notes
|
| analyze() |
Main orchestration |
Runs all 6 algorithms in sequence
|
| _calculate_factor_scores() |
Calculate all 5 factors |
Returns Dict with 5 scores
|
| _calculate_trend_strength_score() |
Factor 2 with penalties/bonuses |
Most complex - many conditions
|
| _calculate_risk_reward_score() |
Factor 5 lookup table |
EXACT boundary comparisons
|
| _apply_institutional_fight_penalty() |
Algorithm 4: 0.7x multiplier |
Check institutional_fight_in_progress
|
| _enforce_a_plus_criteria() |
Algorithm 5: Cap at 79 if not qualified |
3 criteria must ALL pass
|
| _assign_setup_grade() |
Algorithm 6: Score → Grade |
Simple threshold comparison
|
| _calculate_position_sizing() |
Grade → lots, risk% |
TICKET-5: Realistic sizing
|
=== Configuration Constants ===
# Factor Weights (MUST sum to 1.0)
timeframe_alignment_weight = 0.30
trend_strength_weight = 0.20
entry_technique_weight = 0.15
key_level_proximity_weight = 0.20
risk_reward_weight = 0.15
# Penalties
creeper_move_penalty = -50
ma_struggle_penalty = -30
two_day_trend_penalty = -30
phase_mismatch_penalty = -25
ma_distance_penalty = -40
no_key_level_penalty = -50
institutional_fight_multiplier = 0.7
# Bonuses
railroad_trend_bonus = +15
key_level_bonus = +10
clean_entry_bonus = +10
# Grade Thresholds
a_plus_min_score = 90
a_min_score = 80
b_min_score = 70
c_min_score = 60
d_min_score = 50
=== Common Debugging Questions ===
Q: Why is grade capped at B (score 79) even though raw score is higher?
Check A+ criteria:
1. Is timeframe_analysis.aligned = True?
2. Is entry_data['near_ma'] = True?
3. Is market_state.has_two_day_trend = True?
If ANY is False → score capped at 79.
Q: Why is trend_strength score so low?
Check penalties applied:
* is_creeper_move = True? (-50)
* price_ma_struggle = True? (-30)
* has_two_day_trend = False? (-30)
* trend_phase ≠ MIDDLE? (-25)
Multiple penalties can stack!
Q: Why is position_size always 1 except for A+?
TICKET-5 fix: Realistic sizing for Rs 1 lakh capital.
Only A+ setups get 2 lots (premium setups).
Q: How do I trace which penalties were applied?
Check SetupQualityResult.penalties_applied list and analysis_comments.
