Editing Component:Setup Quality Detection (section)

= Setup Quality Detection =
== Purpose ==

'''"How good is this setup? Is it worth trading? Risk:Reward"'''

This component scores every potential trade from 0-100 and assigns a grade (A+ to F). Higher grades get larger position sizes. The scoring uses a 5-factor weighted system with penalties and bonuses.

----

== Trading Market Principle ==

'''"Not all setups are created equal. Grade them, position size them accordingly."'''

* A+ setup = everything aligned, maximum conviction → 2 lots
* Poor setup = missing key factors → 1 lot or skip
* Penalties protect capital → creeper, ma_struggle, wrong phase = reduce score
* Bonuses reward quality → railroad, clean entry, near key level = boost score
* A+ requires ALL criteria → one missing = capped at 79 (no A+)

----

== 5-Factor Weighted Scoring ==

Every setup is scored across 5 factors, each with a specific weight:

{| class="wikitable"
|-
! Factor !! Weight !! What It Measures !! Score Source
|-
| Timeframe Alignment || '''30%''' || Are all timeframes pointing same direction? || MTF alignment_score × 100
|-
| Trend Strength || '''20%''' || Is the trend strong with no adverse conditions? || 100 - penalties + bonuses
|-
| Entry Quality || '''15%''' || Are we entering at a good spot? || Near MA, clean entry bonuses
|-
| Key Level Proximity || '''20%''' || Are we near support/resistance/institutional levels? || Near key level check
|-
| Risk/Reward || '''15%''' || Is the R:R ratio acceptable? || Lookup table
|}

'''Formula:'''
<pre>
Weighted_Score = (TF × 0.30) + (Trend × 0.20) + (Entry × 0.15) + (KeyLevel × 0.20) + (RR × 0.15)
</pre>

----

== Factor Calculations ==

=== Factor 1: Timeframe Alignment (30%) ===

<pre>
Input:  TimeframeAnalysisResult.alignment_score (0-1)
Output: Score 0-100

score = alignment_score × 100
</pre>

=== Factor 2: Trend Strength (20%) ===

Starts at 100, then applies penalties and bonuses:

<pre>
trend_score = 100

// PENALTIES (subtracted)
IF is_creeper_move:        trend_score -= 50
IF price_ma_struggle:      trend_score -= 30
IF NOT has_two_day_trend:  trend_score -= 30
IF trend_phase != MIDDLE:  trend_score -= 25

// BONUSES (added)
IF is_railroad_trend:      trend_score += 15

RETURN clamp(trend_score, 0, 100)
</pre>

=== Factor 3: Entry Quality (15%) ===

<pre>
entry_score = 100

IF near_key_level:    entry_score += 10   // Key level bonus
IF NOT near_ma:       entry_score -= 40   // MA distance penalty
IF clean_entry:       entry_score += 10   // Clean entry bonus

RETURN clamp(entry_score, 0, 100)
</pre>

== Factor 4: Key Level Proximity (20%) ==

'''Major Institutional Levels Only'''

Only Institutional levels are used for <code>near_key_level</code> detection:

{| class="wikitable"
! Level !! Description
|-
| '''PDH/PDL''' || Prior Day High/Low - "ceilings & floors", major makret memory points
|-
| '''200 MA Zone''' || 25pt buffer - MAs are zones/cushions, not skinny lines
|-
| '''Weekly H/L''' || Prior Week High/Low - institutional reference levels
|}

'''Excluded''' (too noisy): Swing levels, 21 MA, Yesterday's Close, HH/HL/LH/LL structure

<pre>
level_score = 100

# TICKET-25: near_key_level uses major levels only (PDH/PDL, 200 MA zone, Weekly H/L)
IF NOT near_key_level AND NOT near_ma:
    level_score -= 50   // Major penalty

RETURN clamp(level_score, 0, 100)
</pre>

=== Factor 5: Risk/Reward (15%) ===

Uses lookup table:

{| class="wikitable"
|-
! R:R Ratio !! Score !! Quality
|-
| < 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 ==

{| class="wikitable"
|-
! Type !! Condition !! Value !! Factor Affected
|-
| '''Penalty''' || Creeper move detected || -50 || Trend Strength
|-
| '''Penalty''' || Price struggling near MA || -30 || Trend Strength
|-
| '''Penalty''' || No two-day trend || -30 || Trend Strength
|-
| '''Penalty''' || Phase != MIDDLE || -25 || Trend Strength
|-
| '''Penalty''' || Not near MA || -40 || Entry Quality
|-
| '''Penalty''' || Not near key level or MA || -50 || Key Level Proximity
|-
| '''Bonus''' || Railroad trend detected || +15 || Trend Strength
|-
| '''Bonus''' || Near key level || +10 || Entry Quality
|-
| '''Bonus''' || Clean entry || +10 || Entry Quality
|}

----

== Institutional Fight Multiplier ==

If institutional fight is in progress, apply 30% penalty:

<pre>
IF institutional_fight_in_progress:
    final_score = weighted_score × 0.70
</pre>

This reduces all scores by 30% when big players are battling.

----

== A+ Criteria Enforcement ==

To get A+ grade, setup must meet ALL three criteria:

{| class="wikitable"
|-
! Criteria !! Requirement
|-
| All Timeframes Aligned || <code>timeframe_analysis.aligned = True</code>
|-
| Entry Near MA || <code>entry_data.near_ma = True</code>
|-
| Two-Day Trend Present || <code>market_state.has_two_day_trend = True</code>
|}

'''If ANY criteria missing:''' Score is capped at 79 (maximum A grade, no A+)

----

== Grade Thresholds ==

{| class="wikitable"
|-
! 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
|}

----

== Example Calculation ==

'''Scenario:''' MTF aligned at 85%, railroad trend, near MA, R:R = 2.5, no two-day trend

<pre>
STEP 1: Calculate Factor Scores
─────────────────────────────────────────────────
Factor 1 (TF Alignment):  85% × 100 = 85.0
Factor 2 (Trend):         100 - 30 (no 2-day) + 15 (railroad) = 85.0
Factor 3 (Entry):         100 + 10 (near MA) = 110 → capped at 100.0
Factor 4 (Key Level):     100.0 (near MA counts)
Factor 5 (R:R):           90.0 (R:R 2.5 is in [2.0-3.0) range)

STEP 2: Apply Weights
─────────────────────────────────────────────────
Weighted = (85×0.30) + (85×0.20) + (100×0.15) + (100×0.20) + (90×0.15)
         = 25.5 + 17.0 + 15.0 + 20.0 + 13.5
         = 91.0

STEP 3: A+ Enforcement
─────────────────────────────────────────────────
Missing two-day trend → Cap at 79.0

FINAL: Score = 79.0, Grade = A
</pre>

----

== Configuration ==

{| class="wikitable"
|-
! Parameter !! Default !! Description
|-
| <code>timeframe_alignment_weight</code> || 0.30 || 30% weight
|-
| <code>trend_strength_weight</code> || 0.20 || 20% weight
|-
| <code>entry_technique_weight</code> || 0.15 || 15% weight
|-
| <code>key_level_proximity_weight</code> || 0.20 || 20% weight
|-
| <code>risk_reward_weight</code> || 0.15 || 15% weight
|-
| <code>creeper_move_penalty</code> || -50 || Creeper penalty
|-
| <code>ma_struggle_penalty</code> || -30 || MA struggle penalty
|-
| <code>two_day_trend_penalty</code> || -30 || Missing 2-day penalty
|-
| <code>phase_mismatch_penalty</code> || -25 || Wrong phase penalty
|-
| <code>institutional_fight_multiplier</code> || 0.70 || 30% reduction
|}

----

== Output ==

'''SetupQualityResult:'''
{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>grade</code> || Enum || A_PLUS, A, B, C, D, F
|-
| <code>score</code> || float || Final score 0-100
|-
| <code>factor_scores</code> || Dict || Individual factor scores
|-
| <code>position_size</code> || int || 1 or 2 lots
|-
| <code>risk_percent</code> || float || Risk % for this grade
|-
| <code>can_auto_trade</code> || bool || Only A+ and A
|-
| <code>penalties_applied</code> || List || Which penalties were applied
|-
| <code>a_plus_criteria_met</code> || bool || All 3 criteria met?
|}

----

== Dependencies ==

'''Upstream:'''
* [[Component:Multi_Timeframe_Analysis|multi_timeframe_analysis.py]] - Provides alignment score (Factor 1)
* [[Component:Market_State_Analysis|market_state_analysis.py]] - Provides creeper, railroad, two-day, phase

'''Downstream:'''
* [[Component:Signal_Generation|signal_generation_trade_management.py]] - Uses grade for filtering

----