Editing Alpha Research1

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

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

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

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

  '''Note''': C/D/F grades are REJECTED by signal_generation (no trade taken).

  === Key Methods (For Developers) ===

  {| class="wikitable"
  |-
  ! 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 ===
  <code>
  # 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
  </code>

  === 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.