Vcp Screener

"""FMP ``/api/v3`` → ``/stable`` URL compatibility shim.

FMP retired the legacy ``/api/v3/`` surface on 2025-08-31; API keys issued
after that date receive ``403 "Legacy Endpoint"`` on every ``/api/v3/`` request.

This helper rewrites a legacy v3-style URL (and its params) to the ``/stable``
equivalent. It is applied ONLY at construction points that build hardcoded v3
URLs and are *not* part of an explicit stable→v3 fallback list. Methods that
already iterate a ``_FMP_ENDPOINTS`` stable→v3 table must NOT route through this
shim, or the v3 fallback entry would be rewritten back to stable and the
fallback contract would break.

Note on endpoint naming: ``/stable`` endpoint names are inconsistent. Most
legacy underscore names resolve, so unmapped endpoints fall through to a 1:1
underscore-preserving swap. But a few endpoints (``sp500_constituent`` and
``earning_calendar``) return **404 on the underscore form for all tiers** —
their live ``/stable`` name is hyphenated (verified 2026-06). Those are pinned
to the hyphenated form in ``_PATH_RENAME_NO_SYMBOL`` below. Do not "modernize"
the underscore-preserving fallthrough wholesale, and do not revert the pinned
endpoints back to underscore.
"""

from __future__ import annotations

from datetime import date, timedelta

_STABLE = "https://financialmodelingprep.com/stable"

# v3 path segment (symbol carried in the path) → /stable path (symbol via ?symbol=)
_PATH_WITH_SYMBOL = {
    "quote": "/quote",
    "profile": "/profile",
    "income-statement": "/income-statement",
    "balance-sheet-statement": "/balance-sheet-statement",
    "cash-flow-statement": "/cash-flow-statement",
    "key-metrics": "/key-metrics",
    "ratios": "/ratios",
    "enterprise-values": "/enterprise-values",
    "market-capitalization": "/market-capitalization",
    "institutional-holder": "/institutional-ownership/symbol-ownership",
    "etf-holder": "/etf-holdings",
    "rating": "/rating",
    "discounted-cash-flow": "/discounted-cash-flow",
}

# v3 path → /stable path for endpoints that carry NO path symbol and whose
# /stable name differs from the v3 name. Explicit because the underscore
# (v3-style) /stable name 404s for these; the hyphenated name is the live one
# (verified 2026-06: /stable/sp500_constituent and /stable/earning_calendar
# both 404; the hyphenated variants are the live endpoints — 200 with a Premium
# key, lower tiers may 402). These override the underscore-preserving fallthrough.
_PATH_RENAME_NO_SYMBOL = {
    "sp500_constituent": "/sp500-constituent",
    "earning_calendar": "/earnings-calendar",
}


def v3_to_stable(url: str, params: dict | None = None) -> tuple[str, dict]:
    """Rewrite a legacy FMP v3 URL to its ``/stable`` equivalent.

    No-op for URLs that do not contain ``/api/v3/``. Unmapped endpoints fall
    back to a 1:1 underscore-preserving path swap; endpoints whose underscore
    ``/stable`` form 404s are pinned to hyphen via ``_PATH_RENAME_NO_SYMBOL``.
    """
    params = {} if params is None else dict(params)

    if "/api/v3/" not in url:
        return url, params

    after = url.split("/api/v3/", 1)[1].rstrip("/")

    # historical-price-full has a dividend sub-path and a price variant
    if after.startswith("historical-price-full/stock_dividend/"):
        params["symbol"] = after[len("historical-price-full/stock_dividend/") :]
        return _STABLE + "/dividends", params
    if after.startswith("historical-price-full/"):
        params["symbol"] = after[len("historical-price-full/") :]
        # The stable EOD endpoint ignores ``timeseries``; convert to a from/to
        # range (2x calendar days covers N trading days with weekend headroom).
        timeseries = params.pop("timeseries", None)
        if timeseries:
            today = date.today()
            params.setdefault("from", (today - timedelta(days=int(timeseries) * 2)).isoformat())
            params.setdefault("to", today.isoformat())
        return _STABLE + "/historical-price-eod/full", params

    # historical/earning_calendar/{symbol} → earnings?symbol=
    if after.startswith("historical/earning_calendar/"):
        params["symbol"] = after[len("historical/earning_calendar/") :]
        return _STABLE + "/earnings", params

    # symbol-in-path endpoints → ?symbol=
    for v3_path, stable_path in _PATH_WITH_SYMBOL.items():
        if after.startswith(v3_path + "/"):
            params["symbol"] = after[len(v3_path) + 1 :]
            return _STABLE + stable_path, params
        if after == v3_path:
            return _STABLE + stable_path, params

    # Explicit hyphenated renames for symbol-less endpoints whose underscore
    # /stable form 404s (must come before the underscore-preserving fallthrough).
    if after in _PATH_RENAME_NO_SYMBOL:
        return _STABLE + _PATH_RENAME_NO_SYMBOL[after], params

    # Best-effort 1:1 swap, preserving the underscore (v3-style) name. Endpoints
    # whose underscore /stable form is known to 404 are pinned to hyphen above.
    return _STABLE + "/" + after, params

# VCP Screener Calculators

#!/usr/bin/env python3
"""
Execution State Engine - Determines whether a VCP candidate is actionable now.

Separates "strong pattern" from "buy-able now":
- Structure Quality (composite_score): How good is the VCP pattern?
- Execution State: Can I actually enter at this price?

States (highest to lowest precedence):
  Invalid      - Price below SMA50 and SMA200 (not in Stage 2)
  Damaged      - Price below stop level or SMA50 violated
  Overextended - Too far from pivot or SMA200 (chase risk)
  Extended     - 5-10% above pivot (elevated risk)
  Early-post-breakout - 3-5% above pivot
  Breakout     - Within 3% of pivot with volume confirmation
  Pre-breakout - Within or below pivot (ideal entry zone)
"""

from typing import Optional


def compute_execution_state(
    distance_from_pivot_pct: Optional[float],
    price: float,
    sma50: Optional[float],
    sma200: Optional[float],
    sma200_distance_pct: Optional[float],
    last_contraction_low: Optional[float],
    breakout_volume: bool,
    max_sma200_extension: float = 50.0,
) -> dict:
    """
    Determine execution state from pre-calculated data.

    Decision tree evaluated top-to-bottom (first match wins):
    1. price < sma50 < sma200            → Invalid
    2. price < last_contraction_low      → Damaged
    3. price < sma50                     → Damaged
    4. sma200_distance > max_sma200_ext  → Overextended
    5. pivot_distance > 10%              → Overextended
    6. pivot_distance 5-10%              → Extended
    7. pivot_distance 3-5%              → Early-post-breakout
    8. pivot_distance 0-3% + volume      → Breakout
    9. pivot_distance 0-3%              → Early-post-breakout (volume unconfirmed)
    10. pivot_distance < 0%              → Pre-breakout

    Args:
        distance_from_pivot_pct: % distance from pivot (positive = above, negative = below)
        price: Current stock price
        sma50: 50-day simple moving average
        sma200: 200-day simple moving average
        sma200_distance_pct: % above SMA200 (positive = above)
        last_contraction_low: Low of the last VCP contraction (stop level)
        breakout_volume: True if today's volume confirms a breakout (1.5x+ avg)
        max_sma200_extension: Max % above SMA200 before Overextended (default 50.0)

    Returns:
        dict with "state" (str) and "reasons" (list[str])
    """
    reasons = []

    # Rule 1: Invalid - not in Stage 2 (price below both moving averages)
    if sma50 is not None and sma200 is not None:
        if price < sma50 and sma50 < sma200:
            reasons.append(f"Price ${price:.2f} < SMA50 ${sma50:.2f} < SMA200 ${sma200:.2f}")
            return {"state": "Invalid", "reasons": reasons}

    # Rule 2: Damaged - stop level violated
    if last_contraction_low is not None and last_contraction_low > 0:
        if price < last_contraction_low:
            reasons.append(
                f"Price ${price:.2f} below last contraction low ${last_contraction_low:.2f}"
            )
            return {"state": "Damaged", "reasons": reasons}

    # Rule 3: Damaged - price below SMA50 (Stage 2 violation)
    if sma50 is not None and price < sma50:
        reasons.append(f"Price ${price:.2f} below SMA50 ${sma50:.2f}")
        return {"state": "Damaged", "reasons": reasons}

    # Rule 4: Overextended - too far above SMA200
    if sma200_distance_pct is not None and sma200_distance_pct > max_sma200_extension:
        reasons.append(
            f"SMA200 distance {sma200_distance_pct:.1f}% > max {max_sma200_extension:.0f}%"
        )
        return {"state": "Overextended", "reasons": reasons}

    # Rules 5-10 require pivot distance
    if distance_from_pivot_pct is None:
        reasons.append("No pivot available")
        return {"state": "Pre-breakout", "reasons": reasons}

    # Rule 5: Overextended - more than 10% above pivot
    if distance_from_pivot_pct > 10.0:
        reasons.append(f"+{distance_from_pivot_pct:.1f}% above pivot (> 10%)")
        return {"state": "Overextended", "reasons": reasons}

    # Rule 6: Extended - 5-10% above pivot
    if distance_from_pivot_pct > 5.0:
        reasons.append(f"+{distance_from_pivot_pct:.1f}% above pivot (5-10% zone)")
        return {"state": "Extended", "reasons": reasons}

    # Rule 7: Early-post-breakout - 3-5% above pivot
    if distance_from_pivot_pct > 3.0:
        reasons.append(f"+{distance_from_pivot_pct:.1f}% above pivot (3-5% zone)")
        return {"state": "Early-post-breakout", "reasons": reasons}

    # Rules 8-9: Within 3% of pivot (or below)
    if distance_from_pivot_pct >= 0.0:
        if breakout_volume:
            reasons.append(f"+{distance_from_pivot_pct:.1f}% above pivot with volume confirmation")
            return {"state": "Breakout", "reasons": reasons}
        else:
            reasons.append(f"+{distance_from_pivot_pct:.1f}% above pivot (volume unconfirmed)")
            return {"state": "Early-post-breakout", "reasons": reasons}

    # Rule 10: Below pivot
    reasons.append(f"{distance_from_pivot_pct:.1f}% below pivot (forming pattern)")
    return {"state": "Pre-breakout", "reasons": reasons}


# State ordering for cap enforcement (lower index = more restrictive)
STATE_ORDER = [
    "Invalid",
    "Damaged",
    "Overextended",
    "Extended",
    "Early-post-breakout",
    "Breakout",
    "Pre-breakout",
]

# Maximum rating allowed per execution state
STATE_MAX_RATING = {
    "Invalid": "No VCP",
    "Damaged": "No VCP",
    "Overextended": "Weak VCP",
    "Extended": "Developing VCP",
    "Early-post-breakout": "Strong VCP",  # Cap: breakout in progress, not yet confirmed
    "Breakout": None,  # No cap
    "Pre-breakout": None,  # No cap
}

# Rating hierarchy (higher index = higher rating)
RATING_ORDER = [
    "No VCP",
    "Weak VCP",
    "Developing VCP",
    "Good VCP",
    "Strong VCP",
    "Textbook VCP",
]


def apply_state_cap(rating: str, execution_state: str) -> tuple[str, bool]:
    """
    Apply the State Cap: if execution state restricts the maximum allowed rating,
    downgrade the rating accordingly.

    Args:
        rating: Current rating string
        execution_state: Execution state string

    Returns:
        (capped_rating: str, cap_applied: bool)
    """
    max_rating = STATE_MAX_RATING.get(execution_state)
    if max_rating is None:
        return rating, False  # No cap for this state

    current_idx = RATING_ORDER.index(rating) if rating in RATING_ORDER else 0
    max_idx = RATING_ORDER.index(max_rating) if max_rating in RATING_ORDER else 0

    if current_idx > max_idx:
        return max_rating, True

    return rating, False

#!/usr/bin/env python3
"""Forward Outcome Calculator — what happened after the VCP was detected.

Used by the historical single-ticker scanner to label each detected VCP with
the trade-outcome it would have produced if entered at the pivot:

- ``breakout``         : close > pivot within max_window_days
- ``stop_hit``         : close < stop within window, before any breakout
- ``timeout``          : neither hit; window expired
- ``insufficient_data``: fewer than 1 forward bar available

Conventions:
- ``historical`` is most-recent-first (index 0 = most recent bar).
- ``as_of_offset`` is the MRF index treated as the detection day; forward bars
  are ``historical[0 : as_of_offset]`` walked oldest-to-newest.
- ``max_gain_pct`` and ``max_loss_pct`` are measured against the as-of close,
  not the pivot; they describe the trajectory regardless of outcome.
"""

from typing import Optional


def calculate_forward_outcome(
    historical_prices: list[dict],
    as_of_offset: int,
    pivot_price: float,
    stop_price: Optional[float] = None,
    max_window_days: int = 60,
) -> dict:
    """Compute the trade outcome for a VCP detected at ``historical_prices[as_of_offset]``.

    Args:
        historical_prices: Most-recent-first OHLCV bars.
        as_of_offset: Index of the detection bar. Forward window is the bars
            with smaller indices (i.e., more recent than the as-of bar).
        pivot_price: Breakout trigger. First forward bar whose close exceeds
            this is the breakout day.
        stop_price: Stop-loss level (typically the last contraction's low). If
            None, stop_hit is never reported. First forward bar whose close
            falls below this — before any breakout — is the stop-hit day.
        max_window_days: Number of forward bars to evaluate (default 60).

    Returns:
        Dict with the schema documented at the top of this module.
    """
    empty = {
        "outcome_type": "insufficient_data",
        "days_to_outcome": None,
        "exit_price": None,
        "exit_date": None,
        "max_gain_pct": None,
        "max_loss_pct": None,
        "pivot_price": pivot_price,
        "stop_price": stop_price,
        "bars_available": 0,
        "bars_evaluated": 0,
    }

    if not historical_prices or as_of_offset <= 0 or as_of_offset >= len(historical_prices):
        return empty

    as_of_close = historical_prices[as_of_offset].get("close")
    if as_of_close in (None, 0):
        return empty

    # Forward bars in oldest-to-newest order (start at the bar right after
    # the as-of bar and walk toward the present).
    forward = list(reversed(historical_prices[:as_of_offset]))
    bars_available = len(forward)
    if bars_available == 0:
        return empty

    window = forward[:max_window_days]

    outcome_type = "timeout"
    days_to_outcome: Optional[int] = None
    exit_price: Optional[float] = None
    exit_date: Optional[str] = None
    max_gain_pct: Optional[float] = None
    max_loss_pct: Optional[float] = None

    # Walk the entire forward window so max_gain / max_loss describe the full
    # trajectory regardless of where the outcome is triggered. The outcome
    # itself is set only at the first triggering bar.
    for i, bar in enumerate(window, start=1):
        close = bar.get("close")
        if close is None:
            continue

        gain_pct = (close - as_of_close) / as_of_close * 100
        if max_gain_pct is None or gain_pct > max_gain_pct:
            max_gain_pct = gain_pct
        if max_loss_pct is None or gain_pct < max_loss_pct:
            max_loss_pct = gain_pct

        if outcome_type == "timeout":
            if close > pivot_price:
                outcome_type = "breakout"
                days_to_outcome = i
                exit_price = close
                exit_date = bar.get("date")
            elif stop_price is not None and close < stop_price:
                outcome_type = "stop_hit"
                days_to_outcome = i
                exit_price = close
                exit_date = bar.get("date")

    return {
        "outcome_type": outcome_type,
        "days_to_outcome": days_to_outcome,
        "exit_price": round(exit_price, 4) if exit_price is not None else None,
        "exit_date": exit_date,
        "max_gain_pct": round(max_gain_pct, 4) if max_gain_pct is not None else None,
        "max_loss_pct": round(max_loss_pct, 4) if max_loss_pct is not None else None,
        "pivot_price": pivot_price,
        "stop_price": stop_price,
        "bars_available": bars_available,
        "bars_evaluated": len(window),
    }

#!/usr/bin/env python3
"""
Pattern Classifier - Categorizes VCP candidates by pattern type.

Separates structural quality (what kind of pattern is this?) from
execution state (can I enter now?). The two axes together give a
complete picture of each candidate.

Pattern Types (priority order, first match wins):
  Damaged         - Invalid/Damaged execution state; setup not viable
  Extended Leader - Valid VCP structure but already extended (>5% above pivot)
  Post-breakout   - Breaking out or just broke out (0-5% above pivot + volume)
  Textbook VCP    - Ideal pre-breakout setup (3+ contractions, tight, dry volume)
  VCP-adjacent    - Some VCP characteristics but not fully textbook-quality
"""

from typing import Optional


def classify_pattern(
    valid_vcp: bool,
    num_contractions: int,
    final_contraction_depth: Optional[float],
    execution_state: str,
    dry_up_ratio: Optional[float],
    wide_and_loose: bool = False,
) -> str:
    """
    Classify the pattern type for a VCP candidate.

    Decision tree (evaluated top-to-bottom, first match wins):
    1. execution_state in (Invalid, Damaged)           → Damaged
    2. valid_vcp + execution_state in (Overextended,
       Extended, Early-post-breakout, Breakout)        → Extended Leader / Post-breakout
    3. not valid_vcp + extended states                 → VCP-adjacent
    4. Pre-breakout + valid + textbook criteria        → Textbook VCP
    5. Pre-breakout + valid (not textbook)             → VCP-adjacent
    6. All other valid patterns                        → VCP-adjacent

    Textbook VCP criteria (ALL must be met):
    - valid_vcp is True
    - not wide_and_loose
    - num_contractions >= 3
    - final_contraction_depth <= 10.0%
    - dry_up_ratio <= 0.7 (significant volume dry-up)
    - execution_state == "Pre-breakout"

    Args:
        valid_vcp: Whether VCP contraction ratios passed validation
        num_contractions: Number of detected contractions
        final_contraction_depth: Depth (%) of the last contraction
        execution_state: Output of compute_execution_state() — e.g. "Pre-breakout"
        dry_up_ratio: Volume dry-up ratio (lower = more dry-up)
        wide_and_loose: True if final contraction is wide/deep (Phase 3 flag)

    Returns:
        Pattern type string: "Textbook VCP" | "VCP-adjacent" |
                             "Post-breakout" | "Extended Leader" | "Damaged"
    """
    # Rule 1: Damaged execution states — setup not viable
    if execution_state in ("Invalid", "Damaged"):
        return "Damaged"

    # Rules 2-3: Extended / post-breakout states
    if execution_state in ("Overextended", "Extended"):
        return "Extended Leader" if valid_vcp else "VCP-adjacent"

    if execution_state in ("Early-post-breakout", "Breakout"):
        return "Post-breakout" if valid_vcp else "VCP-adjacent"

    # Rules 4-6: Pre-breakout (or no-pivot) states
    if not valid_vcp or wide_and_loose:
        return "VCP-adjacent"

    # Check Textbook VCP criteria
    textbook = (
        num_contractions >= 3
        and (final_contraction_depth is None or final_contraction_depth <= 10.0)
        and (dry_up_ratio is not None and dry_up_ratio <= 0.7)
        and execution_state == "Pre-breakout"
    )

    return "Textbook VCP" if textbook else "VCP-adjacent"

#!/usr/bin/env python3
"""
Pivot Proximity Calculator - Breakout Distance & Risk Analysis

Calculates how close the current price is to the VCP pivot (breakout) point
and computes the risk profile for a potential trade.

Distance-priority scoring (Minervini: do not chase >5% above pivot):
- 0-3% above pivot:  90 (+ volume bonus 10 = 100 BREAKOUT CONFIRMED)
- 3-5% above:        65 (+ volume bonus 10 = 75)
- 5-10% above:       50 (no volume bonus)
- 10-20% above:      35 (no volume bonus)
- >20% above:        20 (no volume bonus)
- 0 to -2% below:    90 (AT PIVOT)
- -2% to -5%:        75 (NEAR PIVOT)
- -5% to -8%:        60 (APPROACHING)
- -8% to -10%:       45 (DEVELOPING)
- -10% to -15%:      30 (EARLY)
- < -15%:            10 (FAR FROM PIVOT)

Also calculates:
- Stop-loss price (below last contraction low)
- Risk % per share (entry to stop distance)
"""

from typing import Optional


def calculate_pivot_proximity(
    current_price: float,
    pivot_price: Optional[float],
    last_contraction_low: Optional[float] = None,
    breakout_volume: bool = False,
) -> dict:
    """
    Calculate proximity to pivot point and risk metrics.

    Args:
        current_price: Current stock price
        pivot_price: The pivot (breakout) price from VCP pattern
        last_contraction_low: Low of the last contraction (for stop-loss)
        breakout_volume: Whether current volume is 1.5x+ above average

    Returns:
        Dict with score (0-100), distance_pct, stop_loss, risk_pct
    """
    if not pivot_price or pivot_price <= 0:
        return {
            "score": 0,
            "distance_from_pivot_pct": None,
            "stop_loss_price": None,
            "risk_pct": None,
            "trade_status": "NO PIVOT",
            "error": "No valid pivot price",
        }

    if current_price <= 0:
        return {
            "score": 0,
            "distance_from_pivot_pct": None,
            "stop_loss_price": None,
            "risk_pct": None,
            "trade_status": "INVALID PRICE",
            "error": "Invalid current price",
        }

    # Distance from pivot (negative = below pivot)
    distance_pct = (current_price - pivot_price) / pivot_price * 100

    # Determine trade status and score (distance-priority)
    if distance_pct > 20:
        score = 20
        trade_status = "OVEREXTENDED - Do not chase"
    elif distance_pct > 10:
        score = 35
        trade_status = "EXTENDED - Very high chase risk"
    elif distance_pct > 5:
        score = 50
        trade_status = "EXTENDED - High chase risk"
    elif distance_pct > 3:
        score = 65
        trade_status = "EXTENDED - Moderate chase risk"
    elif distance_pct > 0:
        score = 90
        trade_status = "ABOVE PIVOT (within 3%)"
    elif distance_pct >= -2:
        score = 90
        trade_status = "AT PIVOT (within 2%)"
    elif distance_pct >= -5:
        score = 75
        trade_status = "NEAR PIVOT (2-5% below)"
    elif distance_pct >= -8:
        score = 60
        trade_status = "APPROACHING (5-8% below)"
    elif distance_pct >= -10:
        score = 45
        trade_status = "DEVELOPING (8-10% below)"
    elif distance_pct >= -15:
        score = 30
        trade_status = "EARLY (10-15% below)"
    else:
        score = 10
        trade_status = "FAR FROM PIVOT (>15% below)"

    # Volume confirmation bonus (only for 0-5% above pivot)
    if breakout_volume and distance_pct > 0:
        if distance_pct <= 3:
            score += 10
            trade_status = "BREAKOUT CONFIRMED"
        elif distance_pct <= 5:
            score += 10
            trade_status += " (vol confirmed)"

    # Calculate stop-loss and risk
    stop_loss_price = None
    risk_pct = None

    if last_contraction_low and last_contraction_low > 0:
        # Stop-loss is 1-2% below the last contraction low
        stop_loss_price = round(last_contraction_low * 0.99, 2)

        # Risk per share from current price to stop
        if current_price > stop_loss_price:
            risk_pct = round((current_price - stop_loss_price) / current_price * 100, 2)
        else:
            # Price already below stop level — setup is invalidated
            risk_pct = None
            trade_status = "BELOW STOP LEVEL"
            score = 0

    return {
        "score": score,
        "distance_from_pivot_pct": round(distance_pct, 2),
        "pivot_price": round(pivot_price, 2),
        "stop_loss_price": stop_loss_price,
        "risk_pct": risk_pct,
        "trade_status": trade_status,
        "error": None,
    }

#!/usr/bin/env python3
"""
Relative Strength Calculator - Minervini Weighted RS

Calculates relative price performance vs S&P 500 using Minervini's weighting:
- 40% weight: Last 3 months (63 trading days)
- 20% weight: Last 6 months (126 trading days)
- 20% weight: Last 9 months (189 trading days)
- 20% weight: Last 12 months (252 trading days)

This emphasizes recent momentum more than a simple 52-week calculation.

Scoring:
- 100: Weighted RS outperformance >= +50% (top 1%)
- 95:  >= +30% (top 5%)
- 90:  >= +20% (top 10%)
- 80:  >= +10% (top 20%)
- 70:  >= +5% (top 30%)
- 60:  >= 0% (top 40%)
- 50:  >= -5% (average)
- 40:  >= -10% (below average)
- 20:  >= -20% (weak)
- 0:   < -20% (laggard)
"""

# Minervini weighting periods (trading days) and weights
RS_PERIODS = [
    (63, 0.40),  # 3 months - 40%
    (126, 0.20),  # 6 months - 20%
    (189, 0.20),  # 9 months - 20%
    (252, 0.20),  # 12 months - 20%
]


def calculate_relative_strength(
    stock_prices: list[dict],
    sp500_prices: list[dict],
) -> dict:
    """
    Calculate Minervini-weighted relative strength vs S&P 500.

    Args:
        stock_prices: Daily OHLCV for stock (most recent first), need 252+ days
        sp500_prices: Daily OHLCV for SPY (most recent first), need 252+ days

    Returns:
        Dict with score (0-100), rs_rank_estimate, weighted_rs, period details
    """
    if not stock_prices or len(stock_prices) < 63:
        return {
            "score": 0,
            "rs_rank_estimate": 0,
            "weighted_rs": None,
            "error": "Insufficient stock price data (need 63+ days)",
        }

    if not sp500_prices or len(sp500_prices) < 63:
        return {
            "score": 0,
            "rs_rank_estimate": 0,
            "weighted_rs": None,
            "error": "Insufficient S&P 500 price data (need 63+ days)",
        }

    stock_closes = [d.get("close", d.get("adjClose", 0)) for d in stock_prices]
    sp500_closes = [d.get("close", d.get("adjClose", 0)) for d in sp500_prices]

    weighted_rs = 0.0
    total_weight = 0.0
    period_details = []

    for period_days, weight in RS_PERIODS:
        if len(stock_closes) > period_days and len(sp500_closes) > period_days:
            stock_return = _period_return(stock_closes, period_days)
            sp500_return = _period_return(sp500_closes, period_days)
            relative = stock_return - sp500_return

            weighted_rs += relative * weight
            total_weight += weight

            period_details.append(
                {
                    "period_days": period_days,
                    "weight": weight,
                    "stock_return_pct": round(stock_return, 2),
                    "sp500_return_pct": round(sp500_return, 2),
                    "relative_pct": round(relative, 2),
                }
            )
        elif len(stock_closes) > period_days // 2 and len(sp500_closes) > period_days // 2:
            # Partial data: use available days with reduced weight
            available = min(len(stock_closes) - 1, len(sp500_closes) - 1)
            stock_return = _period_return(stock_closes, available)
            sp500_return = _period_return(sp500_closes, available)
            relative = stock_return - sp500_return
            reduced_weight = weight * 0.5

            weighted_rs += relative * reduced_weight
            total_weight += reduced_weight

            period_details.append(
                {
                    "period_days": period_days,
                    "weight": reduced_weight,
                    "stock_return_pct": round(stock_return, 2),
                    "sp500_return_pct": round(sp500_return, 2),
                    "relative_pct": round(relative, 2),
                    "note": f"Partial data ({available} days available)",
                }
            )

    if total_weight > 0:
        weighted_rs = weighted_rs / total_weight
    else:
        return {
            "score": 0,
            "rs_rank_estimate": 0,
            "weighted_rs": None,
            "error": "Unable to calculate weighted RS (insufficient overlapping data)",
        }

    # Score based on weighted relative performance
    score, rs_rank = _score_rs(weighted_rs)

    return {
        "score": score,
        "rs_rank_estimate": rs_rank,
        "weighted_rs": round(weighted_rs, 2),
        "period_details": period_details,
        "error": None,
    }


def _period_return(closes: list[float], period: int) -> float:
    """Calculate return over period. Closes are most-recent-first."""
    if len(closes) <= period or closes[period] <= 0:
        return 0.0
    return ((closes[0] - closes[period]) / closes[period]) * 100


def rank_relative_strength_universe(rs_results: dict[str, dict]) -> dict[str, dict]:
    """Rank all candidates by weighted_rs and assign percentile-based scores.

    Stocks with weighted_rs=None are excluded from percentile ranking and
    assigned score=0, rs_percentile=0. Small populations (fewer than
    MIN_POPULATION_FOR_FULL_SCORE valid stocks) have their scores capped
    to prevent inflated rankings.

    Args:
        rs_results: {symbol: {score, weighted_rs, ...}} for each candidate

    Returns:
        Updated dict with rs_percentile and recalculated score for each symbol
    """
    if not rs_results:
        return {}

    # Separate valid (weighted_rs is not None) from invalid
    valid_symbols = [s for s in rs_results if rs_results[s].get("weighted_rs") is not None]
    invalid_symbols = [s for s in rs_results if rs_results[s].get("weighted_rs") is None]

    # Handle invalid stocks: score=0, rs_percentile=0
    result = {}
    for sym in invalid_symbols:
        updated = dict(rs_results[sym])
        updated["rs_percentile"] = 0
        updated["score"] = 0
        result[sym] = updated

    if not valid_symbols:
        return result

    # Sort valid symbols by weighted_rs
    valid_symbols.sort(key=lambda s: rs_results[s]["weighted_rs"])

    n = len(valid_symbols)
    # Assign percentiles (handle ties by giving same percentile)
    percentiles = {}
    i = 0
    while i < n:
        current_val = rs_results[valid_symbols[i]]["weighted_rs"]
        j = i + 1
        while j < n and rs_results[valid_symbols[j]]["weighted_rs"] == current_val:
            j += 1
        pct = int(round(j / n * 100))
        for k in range(i, j):
            percentiles[valid_symbols[k]] = pct
        i = j

    # Small population cap: with fewer valid stocks, cap score and percentile
    max_score = _small_population_max_score(n)
    max_percentile = _score_to_max_percentile(max_score)

    for sym in valid_symbols:
        updated = dict(rs_results[sym])
        capped_pct = min(percentiles[sym], max_percentile)
        updated["rs_percentile"] = capped_pct
        updated["score"] = _percentile_to_score(capped_pct)
        result[sym] = updated

    return result


# Minimum population for unrestricted percentile scoring
MIN_POPULATION_FOR_FULL_SCORE = 20


def _small_population_max_score(n: int) -> int:
    """Cap maximum RS score when population is too small for reliable percentiles."""
    if n >= MIN_POPULATION_FOR_FULL_SCORE:
        return 100
    if n >= 10:
        return 90
    if n >= 5:
        return 80
    return 70


def _score_to_max_percentile(max_score: int) -> int:
    """Return the highest percentile that maps to max_score via _percentile_to_score.

    This ensures rs_percentile and score stay consistent when capped.
    """
    if max_score >= 100:
        return 100
    if max_score >= 90:
        return 94  # _percentile_to_score(94) == 90
    if max_score >= 80:
        return 84  # _percentile_to_score(84) == 80
    if max_score >= 70:
        return 74  # _percentile_to_score(74) == 70
    if max_score >= 60:
        return 59
    if max_score >= 50:
        return 44
    if max_score >= 40:
        return 29
    return 14


def _percentile_to_score(percentile: int) -> int:
    """Map percentile rank to RS score."""
    if percentile >= 95:
        return 100
    elif percentile >= 85:
        return 90
    elif percentile >= 75:
        return 80
    elif percentile >= 60:
        return 70
    elif percentile >= 45:
        return 60
    elif percentile >= 30:
        return 50
    elif percentile >= 15:
        return 40
    else:
        return 20


def _score_rs(weighted_rs: float) -> tuple:
    """Score based on weighted relative strength."""
    if weighted_rs >= 50:
        return 100, 99
    elif weighted_rs >= 30:
        return 95, 95
    elif weighted_rs >= 20:
        return 90, 90
    elif weighted_rs >= 10:
        return 80, 80
    elif weighted_rs >= 5:
        return 70, 70
    elif weighted_rs >= 0:
        return 60, 60
    elif weighted_rs >= -5:
        return 50, 50
    elif weighted_rs >= -10:
        return 40, 40
    elif weighted_rs >= -20:
        return 20, 25
    else:
        return 0, 10

#!/usr/bin/env python3
"""
Trend Template Calculator - Minervini's 7-Point Stage 2 Filter

Evaluates whether a stock meets Minervini's Stage 2 uptrend criteria.
This is the primary gate filter - stocks must pass this to be evaluated for VCP.

The 7-Point Trend Template:
1. Price > 150-day SMA AND Price > 200-day SMA
2. 150-day SMA > 200-day SMA
3. 200-day SMA trending up for at least 22 trading days (1 month)
4. Price > 50-day SMA
5. Price at least 25% above 52-week low
6. Price within 25% of 52-week high
7. Relative Strength rating > 70 (estimated)

Scoring: Each criterion = 14.3 points (7 x 14.3 = ~100)
Pass threshold: >= 85 (must meet at least 6 of 7 criteria)
"""

from typing import Optional


def calculate_trend_template(
    historical_prices: list[dict],
    quote_data: dict,
    rs_rank: Optional[int] = None,
    ext_threshold: float = 8.0,
    max_sma200_extension: float = 50.0,
) -> dict:
    """
    Evaluate stock against Minervini's 7-point Trend Template.

    Args:
        historical_prices: Daily OHLCV data (most recent first), need 200+ days
        quote_data: Current quote with price, yearHigh, yearLow
        rs_rank: Pre-calculated RS rank estimate (0-99). If None, criterion 7 is skipped.

    Returns:
        Dict with score (0-100), criteria details, pass/fail status
    """
    if not historical_prices or len(historical_prices) < 50:
        return {
            "score": 0,
            "passed": False,
            "criteria": {},
            "error": "Insufficient historical data (need 50+ days)",
        }

    closes = [d.get("close", d.get("adjClose", 0)) for d in historical_prices]
    price = quote_data.get("price", closes[0] if closes else 0)
    year_high = quote_data.get("yearHigh", 0)
    year_low = quote_data.get("yearLow", 0)

    criteria = {}
    points_per_criterion = 14.3

    # Criterion 1: Price > SMA150 AND Price > SMA200
    sma150 = _sma(closes, 150)
    sma200 = _sma(closes, 200)
    c1_pass = False
    if sma150 is not None and sma200 is not None:
        c1_pass = price > sma150 and price > sma200
    elif sma150 is not None:
        c1_pass = price > sma150
    if sma150 is not None:
        c1_detail = f"Price ${price:.2f} vs SMA150 ${sma150:.2f}"
        if sma200 is not None:
            c1_detail += f" / SMA200 ${sma200:.2f}"
    else:
        c1_detail = "Insufficient data for SMA150"
    criteria["c1_price_above_sma150_200"] = {
        "passed": c1_pass,
        "detail": c1_detail,
    }

    # Criterion 2: SMA150 > SMA200
    c2_pass = False
    if sma150 is not None and sma200 is not None:
        c2_pass = sma150 > sma200
    criteria["c2_sma150_above_sma200"] = {
        "passed": c2_pass,
        "detail": f"SMA150 ${sma150:.2f} vs SMA200 ${sma200:.2f}"
        if sma150 and sma200
        else "Insufficient data",
    }

    # Criterion 3: SMA200 trending up for 22+ trading days
    c3_pass = False
    if len(closes) >= 222 and sma200 is not None:
        sma200_22d_ago = _sma(closes[22:], 200)
        if sma200_22d_ago is not None:
            c3_pass = sma200 > sma200_22d_ago
            criteria["c3_sma200_trending_up"] = {
                "passed": c3_pass,
                "detail": f"SMA200 today ${sma200:.2f} vs 22d ago ${sma200_22d_ago:.2f}",
            }
        else:
            criteria["c3_sma200_trending_up"] = {
                "passed": False,
                "detail": "Insufficient data for 22d SMA200 comparison",
            }
    elif sma200 is not None and len(closes) >= 200:
        # Not enough data to compute SMA200 from 22 days ago - fail conservatively
        c3_pass = False
        criteria["c3_sma200_trending_up"] = {
            "passed": c3_pass,
            "detail": f"Cannot verify 22d SMA200 trend (only {len(closes)} days available, need 222+)",
        }
    else:
        criteria["c3_sma200_trending_up"] = {
            "passed": False,
            "detail": "Insufficient data",
        }

    # Criterion 4: Price > SMA50
    sma50 = _sma(closes, 50)
    c4_pass = False
    if sma50 is not None:
        c4_pass = price > sma50
    criteria["c4_price_above_sma50"] = {
        "passed": c4_pass,
        "detail": f"Price ${price:.2f} vs SMA50 ${sma50:.2f}" if sma50 else "Insufficient data",
    }

    # Criterion 5: Price at least 25% above 52-week low
    c5_pass = False
    if year_low > 0:
        pct_above_low = (price - year_low) / year_low * 100
        c5_pass = pct_above_low >= 25
        criteria["c5_25pct_above_52w_low"] = {
            "passed": c5_pass,
            "detail": f"{pct_above_low:.1f}% above 52w low ${year_low:.2f} (need >= 25%)",
        }
    else:
        criteria["c5_25pct_above_52w_low"] = {
            "passed": False,
            "detail": "52-week low data unavailable",
        }

    # Criterion 6: Price within 25% of 52-week high
    c6_pass = False
    if year_high > 0:
        pct_below_high = (year_high - price) / year_high * 100
        c6_pass = pct_below_high <= 25
        criteria["c6_within_25pct_52w_high"] = {
            "passed": c6_pass,
            "detail": f"{pct_below_high:.1f}% below 52w high ${year_high:.2f} (need <= 25%)",
        }
    else:
        criteria["c6_within_25pct_52w_high"] = {
            "passed": False,
            "detail": "52-week high data unavailable",
        }

    # Criterion 7: RS Rating > 70
    c7_pass = False
    if rs_rank is not None:
        c7_pass = rs_rank > 70
        criteria["c7_rs_rank_above_70"] = {
            "passed": c7_pass,
            "detail": f"RS Rank: {rs_rank} (need > 70)",
        }
    else:
        criteria["c7_rs_rank_above_70"] = {
            "passed": False,
            "detail": "RS Rank not yet calculated",
        }

    # Raw score from 7 criteria (gate判定用)
    passed_count = sum(1 for c in criteria.values() if c["passed"])
    raw_score = round(passed_count * points_per_criterion, 1)
    raw_score = min(100, raw_score)

    # Pass threshold: 85+ (6/7 criteria) - uses RAW score only
    passed = raw_score >= 85

    # Extended penalty: deduct for price too far above SMA50 (ranking用)
    extended_penalty, sma50_distance_pct = _calculate_extended_penalty(
        price, sma50, base_threshold=ext_threshold
    )

    # SMA200 extension penalty: deduct for price too far above SMA200
    sma200_penalty, sma200_distance_pct = _calculate_sma200_penalty(
        price, sma200, max_extension=max_sma200_extension
    )

    # SMA200 penalty excluded from score to avoid double-penalizing
    # with execution_state (which already uses sma200_distance_pct for
    # Overextended classification). SMA200 penalty kept as metadata.
    score = max(0, raw_score + extended_penalty)

    return {
        "score": score,
        "raw_score": raw_score,
        "passed": passed,
        "extended_penalty": extended_penalty,
        "sma200_penalty": sma200_penalty,
        "sma50_distance_pct": round(sma50_distance_pct, 2)
        if sma50_distance_pct is not None
        else None,
        "sma200_distance_pct": round(sma200_distance_pct, 2)
        if sma200_distance_pct is not None
        else None,
        "criteria_passed": passed_count,
        "criteria_total": 7,
        "criteria": criteria,
        "sma50": round(sma50, 2) if sma50 else None,
        "sma150": round(sma150, 2) if sma150 else None,
        "sma200": round(sma200, 2) if sma200 else None,
        "error": None,
    }


def _calculate_sma200_penalty(
    price: float,
    sma200: Optional[float],
    max_extension: float = 50.0,
) -> tuple:
    """Calculate penalty for price extended too far above SMA200.

    Penalises highly extended leaders where the uptrend is likely to pause
    or mean-revert before a fresh VCP base can form.

    Penalty tiers (measured from max_extension threshold, default 50%):
        distance > max+20% (default >70%) → −20
        distance > max+10% (default >60%) → −15
        distance > max     (default >50%) → −10
        distance > max−10% (default >40%) → −5
        distance ≤ max−10%               →  0

    Args:
        price: Current stock price
        sma200: 200-day simple moving average
        max_extension: % above SMA200 where the first penalty tier starts

    Returns:
        (penalty: int, distance_pct: float or None)
        penalty is 0 or negative.
    """
    if sma200 is None or sma200 <= 0:
        return 0, None

    distance_pct = (price - sma200) / sma200 * 100

    # No penalty when below max_extension
    if distance_pct <= max_extension:
        return 0, distance_pct

    excess = distance_pct - max_extension
    if excess >= 20:
        return -20, distance_pct
    elif excess >= 10:
        return -15, distance_pct
    else:
        return -10, distance_pct


def _calculate_extended_penalty(
    price: float, sma50: Optional[float], base_threshold: float = 8.0
) -> tuple:
    """Calculate penalty for price extended too far above SMA 50.

    Args:
        price: Current stock price
        sma50: 50-day simple moving average
        base_threshold: Distance % where penalty starts (default 8.0)

    Returns:
        (penalty: int, distance_pct: float or None)
        penalty is 0 or negative.
    """
    if sma50 is None or sma50 <= 0:
        return 0, None

    distance_pct = (price - sma50) / sma50 * 100

    if distance_pct < base_threshold:
        return 0, distance_pct

    excess = distance_pct - base_threshold
    if excess >= 17:  # base+17% (default: 25%+)
        return -20, distance_pct
    elif excess >= 10:  # base+10% (default: 18%+)
        return -15, distance_pct
    elif excess >= 4:  # base+4%  (default: 12%+)
        return -10, distance_pct
    else:  # base+0%  (default: 8%+)
        return -5, distance_pct


def _sma(prices: list[float], period: int) -> Optional[float]:
    """Calculate Simple Moving Average. Prices are most-recent-first."""
    if len(prices) < period:
        return None
    return sum(prices[:period]) / period

#!/usr/bin/env python3
"""
VCP Pattern Calculator - Core Volatility Contraction Pattern Detection

Implements Mark Minervini's VCP detection algorithm:
1. Find swing highs and lows within a 120-day lookback window
2. Identify successive contractions (T1, T2, T3, T4)
3. Validate that each contraction is tighter than the previous
4. Score based on number of contractions, tightness, and depth ratios

VCP Characteristics:
- T1 (first correction): 8-35% depth for S&P 500 large-caps
- Each successive contraction should be 25%+ tighter than the previous
- Minimum 2 contractions required for valid VCP
- Successive highs should be within 5% of each other
- Pattern duration: 15-325 trading days
"""

from typing import Optional


def calculate_vcp_pattern(
    historical_prices: list[dict],
    lookback_days: int = 120,
    atr_multiplier: float = 1.5,
    atr_period: int = 14,
    min_contraction_days: int = 5,
    min_contractions: int = 2,
    t1_depth_min: float = 8.0,
    contraction_ratio: float = 0.75,
    wide_and_loose_threshold: float = 15.0,
) -> dict:
    """
    Detect Volatility Contraction Pattern in price data.

    Uses ATR-based ZigZag swing detection with fallback to fixed-window method.
    Tries multiple starting highs (multi-start) and selects the best pattern.

    Args:
        historical_prices: Daily OHLCV data (most recent first), need 30+ days
        lookback_days: Number of days to look back for pattern (default 120)
        atr_multiplier: ATR multiplier for ZigZag swing threshold
        atr_period: ATR calculation period
        min_contraction_days: Minimum days for a contraction to count
        wide_and_loose_threshold: Final contraction depth % above which (combined
            with <10-day duration) flags a wide-and-loose pattern (default 15.0)

    Returns:
        Dict with score (0-100), contractions list, pattern validity, pivot point,
        atr_compression_ratio, wide_and_loose, right_side_range_ratio
    """
    empty_result = {
        "score": 0,
        "valid_vcp": False,
        "contractions": [],
        "num_contractions": 0,
        "pivot_price": None,
        "atr_compression_ratio": None,
        "wide_and_loose": False,
        "right_side_range_ratio": None,
        "error": None,
    }

    if not historical_prices or len(historical_prices) < 30:
        empty_result["error"] = "Insufficient data (need 30+ days)"
        return empty_result

    # Work in chronological order (oldest first)
    prices = list(reversed(historical_prices[:lookback_days]))
    n = len(prices)

    if n < 30:
        empty_result["error"] = "Insufficient data in lookback window"
        return empty_result

    # Extract price arrays
    highs = [d.get("high", d.get("close", 0)) for d in prices]
    lows = [d.get("low", d.get("close", 0)) for d in prices]
    closes = [d.get("close", 0) for d in prices]
    dates = [d.get("date", f"day-{i}") for i, d in enumerate(prices)]

    # Step A: Find swing points using ZigZag (primary) with fixed-window fallback
    atr_val = _calculate_atr(highs, lows, closes, atr_period)
    atr_10 = _calculate_atr(highs, lows, closes, 10)
    atr_50 = _calculate_atr(highs, lows, closes, 50)
    zz_highs, zz_lows = _zigzag_swing_points(highs, lows, closes, dates, atr_multiplier, atr_period)

    # Use ZigZag results if they have enough points, otherwise fallback
    if len(zz_highs) >= 1 and len(zz_lows) >= 1:
        swing_highs = zz_highs
        swing_lows = zz_lows
    else:
        swing_highs = _find_swing_highs(highs, window=5)
        swing_lows = _find_swing_lows(lows, window=5)

    if len(swing_highs) < 1 or len(swing_lows) < 1:
        empty_result["error"] = "Insufficient swing points detected"
        return empty_result

    # Step B: Multi-start contraction detection
    # Try top 3 swing highs as starting points, pick the best pattern
    sorted_highs = sorted(swing_highs, key=lambda x: x[1], reverse=True)
    best_contractions = []
    best_score = -1
    best_valid = False

    for start_high in sorted_highs[:3]:
        candidate = _build_contractions_from(
            start_high,
            swing_highs,
            swing_lows,
            highs,
            lows,
            dates,
            min_contraction_days=min_contraction_days,
        )
        if len(candidate) >= min_contractions:
            v = _validate_vcp(candidate, n, min_contractions, t1_depth_min, contraction_ratio)
            s = _score_vcp(candidate, v)
        else:
            v = {"valid": False}
            s = 0
        # Compare: valid first, then score, then length as tiebreaker
        key = (int(v.get("valid", False)), s, len(candidate))
        best_key = (int(best_valid), best_score, len(best_contractions))
        if key > best_key:
            best_contractions = candidate
            best_score = s
            best_valid = v.get("valid", False)

    contractions = best_contractions

    if len(contractions) < min_contractions:
        atr_compression_ratio = (atr_10 / atr_50) if (atr_50 > 0 and atr_10 > 0) else None
        return {
            "score": 0,
            "valid_vcp": False,
            "contractions": contractions,
            "num_contractions": len(contractions),
            "pivot_price": _get_pivot_price(contractions, highs, swing_highs),
            "atr_value": round(atr_val, 4) if atr_val else None,
            "atr_compression_ratio": round(atr_compression_ratio, 3)
            if atr_compression_ratio is not None
            else None,
            "wide_and_loose": False,
            "right_side_range_ratio": None,
            "error": f"Fewer than {min_contractions} contractions found",
        }

    # Step C: Validate VCP
    validation = _validate_vcp(contractions, n, min_contractions, t1_depth_min, contraction_ratio)

    # Pivot price = high of the last contraction
    pivot_price = _get_pivot_price(contractions, highs, swing_highs)

    # Calculate pattern duration
    first_idx = contractions[0]["high_idx"]
    last_low_idx = contractions[-1]["low_idx"]
    pattern_duration = last_low_idx - first_idx

    # Score the pattern
    score = _score_vcp(contractions, validation)

    # ATR compression ratio: recent ATR(10) / ATR(50) — lower = more compressed
    atr_compression_ratio: Optional[float] = None
    if atr_10 > 0 and atr_50 > 0:
        atr_compression_ratio = atr_10 / atr_50

    # Wide-and-loose flag: final contraction is deep AND very short
    wide_and_loose = _compute_wide_and_loose(contractions, wide_and_loose_threshold)

    # Right-side tightness: 15-bar price range / ATR(50)
    # Measures how compact the right side of the base is (lower = tighter)
    right_side_range_ratio: Optional[float] = None
    if atr_50 > 0 and n >= 15:
        recent_range = max(highs[-15:]) - min(lows[-15:])
        right_side_range_ratio = recent_range / atr_50

    return {
        "score": score,
        "valid_vcp": validation["valid"],
        "contractions": contractions,
        "num_contractions": len(contractions),
        "pivot_price": round(pivot_price, 2) if pivot_price else None,
        "pattern_duration_days": pattern_duration,
        "validation": validation,
        "atr_value": round(atr_val, 4) if atr_val else None,
        "atr_compression_ratio": round(atr_compression_ratio, 3)
        if atr_compression_ratio is not None
        else None,
        "wide_and_loose": wide_and_loose,
        "right_side_range_ratio": round(right_side_range_ratio, 3)
        if right_side_range_ratio is not None
        else None,
        "error": None,
    }


def _calculate_atr(
    highs: list[float],
    lows: list[float],
    closes: list[float],
    period: int = 14,
) -> float:
    """Calculate Average True Range.

    Args:
        highs: High prices in chronological order (oldest first)
        lows: Low prices in chronological order
        closes: Close prices in chronological order
        period: ATR period (default 14)

    Returns:
        ATR value, or 0.0 if insufficient data
    """
    n = len(highs)
    if n < period + 1:
        return 0.0

    true_ranges = []
    for i in range(1, n):
        tr = max(
            highs[i] - lows[i],
            abs(highs[i] - closes[i - 1]),
            abs(lows[i] - closes[i - 1]),
        )
        true_ranges.append(tr)

    if len(true_ranges) < period:
        return 0.0

    # Simple moving average of true ranges for the last `period` values
    return sum(true_ranges[-period:]) / period


def _zigzag_swing_points(
    highs: list[float],
    lows: list[float],
    closes: list[float],
    dates: list[str],
    atr_multiplier: float = 1.5,
    atr_period: int = 14,
) -> tuple:
    """ATR-based ZigZag swing detection.

    Reversal is recognized only when price moves ATR * multiplier from
    the current extreme. This filters out noise while adapting to volatility.

    Args:
        highs: High prices (chronological, oldest first)
        lows: Low prices (chronological, oldest first)
        closes: Close prices (chronological, oldest first)
        dates: Date strings (chronological, oldest first)
        atr_multiplier: Multiplier for ATR threshold
        atr_period: ATR calculation period

    Returns:
        (swing_highs: [(idx, val)], swing_lows: [(idx, val)])
    """
    n = len(highs)
    if n < atr_period + 1:
        return [], []

    atr = _calculate_atr(highs, lows, closes, atr_period)
    if atr <= 0:
        return [], []

    threshold = atr * atr_multiplier

    swing_highs = []
    swing_lows = []

    # Start by finding initial direction from first few bars
    direction = 1  # 1 = looking for high, -1 = looking for low
    extreme_idx = 0
    extreme_val = highs[0]

    # Find initial extreme
    for i in range(min(atr_period, n)):
        if highs[i] > extreme_val:
            extreme_val = highs[i]
            extreme_idx = i

    direction = 1  # Start looking for a swing high
    extreme_val = highs[extreme_idx]

    for i in range(extreme_idx + 1, n):
        if direction == 1:  # Looking for swing high
            if highs[i] > extreme_val:
                extreme_val = highs[i]
                extreme_idx = i
            elif extreme_val - lows[i] >= threshold:
                # Swing high confirmed at extreme_idx
                swing_highs.append((extreme_idx, extreme_val))
                # Start looking for swing low
                direction = -1
                extreme_val = lows[i]
                extreme_idx = i
        else:  # direction == -1, looking for swing low
            if lows[i] < extreme_val:
                extreme_val = lows[i]
                extreme_idx = i
            elif highs[i] - extreme_val >= threshold:
                # Swing low confirmed at extreme_idx
                swing_lows.append((extreme_idx, extreme_val))
                # Start looking for swing high
                direction = 1
                extreme_val = highs[i]
                extreme_idx = i

    return swing_highs, swing_lows


def _find_swing_highs(highs: list[float], window: int = 5) -> list[tuple[int, float]]:
    """Find swing high points using fixed window. Returns list of (index, value)."""
    swing_highs = []
    for i in range(window, len(highs) - window):
        is_high = True
        for j in range(1, window + 1):
            if highs[i] <= highs[i - j] or highs[i] <= highs[i + j]:
                is_high = False
                break
        if is_high:
            swing_highs.append((i, highs[i]))
    return swing_highs


def _find_swing_lows(lows: list[float], window: int = 5) -> list[tuple[int, float]]:
    """Find swing low points using fixed window. Returns list of (index, value)."""
    swing_lows = []
    for i in range(window, len(lows) - window):
        is_low = True
        for j in range(1, window + 1):
            if lows[i] >= lows[i - j] or lows[i] >= lows[i + j]:
                is_low = False
                break
        if is_low:
            swing_lows.append((i, lows[i]))
    return swing_lows


def _identify_contractions(
    swing_highs: list[tuple[int, float]],
    swing_lows: list[tuple[int, float]],
    highs: list[float],
    lows: list[float],
    dates: list[str],
) -> list[dict]:
    """
    Identify successive contractions from swing points.
    Each contraction is defined by a swing high followed by a swing low.
    """
    if not swing_highs:
        return []

    # Start from the highest swing high in the lookback
    h1_idx, h1_val = max(swing_highs, key=lambda x: x[1])

    contractions = []
    current_high_idx = h1_idx
    current_high_val = h1_val

    # Find successive contraction pairs
    for _ in range(4):  # Max 4 contractions
        # Find next swing low after current high
        next_low = None
        for idx, val in swing_lows:
            if idx > current_high_idx:
                next_low = (idx, val)
                break

        if next_low is None:
            break

        low_idx, low_val = next_low
        depth_pct = (
            (current_high_val - low_val) / current_high_val * 100 if current_high_val > 0 else 0
        )

        contractions.append(
            {
                "label": f"T{len(contractions) + 1}",
                "high_idx": current_high_idx,
                "high_price": round(current_high_val, 2),
                "high_date": dates[current_high_idx] if current_high_idx < len(dates) else "N/A",
                "low_idx": low_idx,
                "low_price": round(low_val, 2),
                "low_date": dates[low_idx] if low_idx < len(dates) else "N/A",
                "depth_pct": round(depth_pct, 2),
            }
        )

        # Find next swing high after this low (for the next contraction)
        next_high = None
        for idx, val in swing_highs:
            if idx > low_idx:
                next_high = (idx, val)
                break

        if next_high is None:
            break

        current_high_idx, current_high_val = next_high

    return contractions


def _build_contractions_from(
    start_high: tuple[int, float],
    swing_highs: list[tuple[int, float]],
    swing_lows: list[tuple[int, float]],
    highs: list[float],
    lows: list[float],
    dates: list[str],
    min_contraction_days: int = 5,
) -> list[dict]:
    """Build contraction sequence from a specific swing high starting point.

    Args:
        start_high: (index, value) of starting swing high
        swing_highs: All swing highs
        swing_lows: All swing lows
        highs: All high prices
        lows: All low prices
        dates: All dates
        min_contraction_days: Minimum days between high and low for a contraction
    """
    h1_idx, h1_val = start_high
    contractions = []
    current_high_idx = h1_idx
    current_high_val = h1_val

    for _ in range(4):  # Max 4 contractions
        # Find next swing low after current high
        next_low = None
        for idx, val in swing_lows:
            if idx > current_high_idx:
                next_low = (idx, val)
                break

        if next_low is None:
            break

        low_idx, low_val = next_low
        duration = low_idx - current_high_idx

        # Skip contractions that are too short
        if duration < min_contraction_days:
            # Find the next swing high after current_high to bound the search
            next_high_boundary = None
            for idx, val in swing_highs:
                if idx > current_high_idx:
                    next_high_boundary = idx
                    break

            # Try to find a later swing low, but only before the next swing high
            found_valid = False
            for idx, val in swing_lows:
                if idx > current_high_idx and (idx - current_high_idx) >= min_contraction_days:
                    if next_high_boundary is not None and idx > next_high_boundary:
                        break  # Don't jump past an intermediate swing high
                    next_low = (idx, val)
                    low_idx, low_val = next_low
                    duration = low_idx - current_high_idx
                    found_valid = True
                    break
            if not found_valid:
                break

        depth_pct = (
            (current_high_val - low_val) / current_high_val * 100 if current_high_val > 0 else 0
        )

        # Right-shoulder validation: subsequent highs within 5% of H1
        if contractions:
            pct_from_h1 = abs(current_high_val - h1_val) / h1_val * 100
            if pct_from_h1 > 5:
                break

        contractions.append(
            {
                "label": f"T{len(contractions) + 1}",
                "high_idx": current_high_idx,
                "high_price": round(current_high_val, 2),
                "high_date": dates[current_high_idx] if current_high_idx < len(dates) else "N/A",
                "low_idx": low_idx,
                "low_price": round(low_val, 2),
                "low_date": dates[low_idx] if low_idx < len(dates) else "N/A",
                "depth_pct": round(depth_pct, 2),
                "duration_days": duration,
            }
        )

        # Find next swing high after this low
        next_high = None
        for idx, val in swing_highs:
            if idx > low_idx:
                next_high = (idx, val)
                break

        if next_high is None:
            break

        current_high_idx, current_high_val = next_high

    return contractions


def _validate_vcp(
    contractions: list[dict],
    total_days: int,
    min_contractions: int = 2,
    t1_depth_min: float = 8.0,
    contraction_ratio: float = 0.75,
) -> dict:
    """Validate whether the contraction pattern qualifies as a VCP."""
    issues = []
    valid = True

    if len(contractions) < min_contractions:
        return {"valid": False, "issues": [f"Need at least {min_contractions} contractions"]}

    # Check T1 depth (8-35% for large-caps)
    t1_depth = contractions[0]["depth_pct"]
    if t1_depth < t1_depth_min:
        issues.append(f"T1 depth too shallow ({t1_depth:.1f}%, need >= {t1_depth_min}%)")
        valid = False
    elif t1_depth > 35:
        issues.append(f"T1 depth too deep ({t1_depth:.1f}%, prefer <= 35%)")
        # Don't invalidate, just flag

    # Check contraction tightening (each T should be <= 75% of previous)
    contraction_ratios = []
    for i in range(1, len(contractions)):
        prev_depth = contractions[i - 1]["depth_pct"]
        curr_depth = contractions[i]["depth_pct"]
        if prev_depth > 0:
            ratio = curr_depth / prev_depth
            contraction_ratios.append(ratio)
            if ratio > contraction_ratio:
                issues.append(
                    f"{contractions[i]['label']} ({curr_depth:.1f}%) does not contract "
                    f"vs {contractions[i - 1]['label']} ({prev_depth:.1f}%), "
                    f"ratio={ratio:.2f} (need <= {contraction_ratio})"
                )
                valid = False

    # Check successive highs within 5% of each other
    for i in range(1, len(contractions)):
        prev_high = contractions[i - 1]["high_price"]
        curr_high = (
            contractions[i]["high_price"]
            if i < len(contractions)
            else contractions[-1]["high_price"]
        )
        # The high of subsequent contraction should be near the first
        if prev_high > 0:
            pct_diff = (
                abs(curr_high - contractions[0]["high_price"]) / contractions[0]["high_price"] * 100
            )
            if pct_diff > 5:
                issues.append(
                    f"{contractions[i]['label']} high ${curr_high:.2f} is "
                    f"{pct_diff:.1f}% from H1 ${contractions[0]['high_price']:.2f}"
                )

    # Pattern duration check (15-325 trading days)
    if len(contractions) >= 2:
        duration = contractions[-1]["low_idx"] - contractions[0]["high_idx"]
        if duration < 15:
            issues.append(f"Pattern too short ({duration} days, need >= 15)")
            valid = False
        elif duration > 325:
            issues.append(f"Pattern too long ({duration} days, prefer <= 325)")

    return {
        "valid": valid,
        "issues": issues,
        "contraction_ratios": [round(r, 3) for r in contraction_ratios],
        "t1_depth": t1_depth,
    }


def _compute_wide_and_loose(contractions: list[dict], threshold: float) -> bool:
    """Return True if the final contraction is wide-and-loose.

    Wide-and-loose: depth > threshold AND duration < 10 days.
    This flags patterns where the final consolidation is too deep and
    too brief to be a quality VCP setup.

    Args:
        contractions: List of contraction dicts (must have depth_pct, duration_days)
        threshold: Maximum acceptable depth % (final contraction)

    Returns:
        True if final contraction qualifies as wide-and-loose
    """
    if not contractions:
        return False
    final = contractions[-1]
    final_depth = final.get("depth_pct", 0.0)
    final_duration = final.get("duration_days", 999)
    return final_depth > threshold and final_duration < 10


def _get_pivot_price(
    contractions: list[dict],
    highs: list[float],
    swing_highs: list[tuple[int, float]],
) -> Optional[float]:
    """Get the pivot (breakout) price - high of the last contraction."""
    if contractions:
        return contractions[-1]["high_price"]
    elif swing_highs:
        return swing_highs[-1][1]
    return None


def _score_vcp(contractions: list[dict], validation: dict) -> int:
    """Score the VCP pattern quality (0-100)."""
    if not validation["valid"]:
        # Even invalid patterns get partial credit for structure
        return min(40, len(contractions) * 15)

    num = len(contractions)

    # Base score by contraction count
    if num >= 4:
        base = 90
    elif num >= 3:
        base = 80
    elif num >= 2:
        base = 60
    else:
        return 20

    score = base

    # Bonus: tight final contraction (< 5% depth)
    final_depth = contractions[-1]["depth_pct"]
    if final_depth < 5:
        score += 10

    # Bonus: good contraction ratio (avg < 0.4 of T1)
    ratios = validation.get("contraction_ratios", [])
    if ratios and sum(ratios) / len(ratios) < 0.4:
        score += 10

    # Penalty: deep T1 (> 30%)
    t1_depth = validation.get("t1_depth", 0)
    if t1_depth > 30:
        score -= 10

    return max(0, min(100, score))