equity-aggregator 0.1.1__py3-none-any.whl → 0.1.5__py3-none-any.whl

equity_aggregator/domain/_utils/_merge.py

@@ -1,459 +1,312 @@
 # _utils/_merge.py
 
 
-from collections import Counter
 from collections.abc import Sequence
 from decimal import Decimal
-from functools import cache
-from itertools import chain
-from statistics import median
-
-from rapidfuzz import fuzz
+from functools import partial
+from typing import NamedTuple
 
 from equity_aggregator.schemas.raw import RawEquity
 
-
-def merge(group: Sequence[RawEquity]) -> RawEquity:
-    """
-    Merges a group of duplicate RawEquity records into a single representative record.
-
-    For each field, a representative value is computed as follows:
-      - name: Clustered by fuzzy similarity; selecting most frequent, earliest spelling.
-      - symbol: Most frequent symbol; ties broken by first occurrence.
-      - isin, cusip, cik, share_class_figi: Most frequent value; ties broken by order.
-      - mics: Union of all non-null lists, order-preserving and duplicates removed.
-      - currency: Most frequent non-null value; ties broken by first occurrence.
-      - last_price: Median of all non-null values.
-      - market_cap: Median of all non-null values.
-
-    Note:
-        This function requires that the input group is non-empty and that all RawEquity
-        objects in the group share the same identical share_class_figi. If these
-        conditions are not met, a ValueError will be raised. This is an enforced
-        constraint to prevent merging heterogeneous equity records.
-
-    Args:
-        group (Sequence[RawEquity]): A sequence of RawEquity objects considered
-            duplicates to be merged.
-
-    Returns:
-        RawEquity: A new RawEquity instance with merged field values.
+from ._merge_config import (
+    FIELD_CONFIG,
+    PRICE_RANGE_FIELDS,
+    FieldSpec,
+    Strategy,
+)
+from ._strategies import (
+    filter_by_deviation,
+    fuzzy_cluster_mode,
+    median_decimal,
+    mode_first,
+    union_ordered,
+)
+
+
+def _extract_field(
+    group: Sequence[RawEquity],
+    field: str,
+    *,
+    filter_none: bool = True,
+) -> list:
     """
+    Extract field values from a group of RawEquity objects.
 
-    # validate share_class_figi consistency first
-    share_class_figi_value = _validate_share_class_figi(group)
-
-    return RawEquity(
-        name=_merge_name(group),
-        symbol=_merge_symbol(group),
-        isin=_merge_id(group, "isin"),
-        cusip=_merge_id(group, "cusip"),
-        cik=_merge_id(group, "cik"),
-        share_class_figi=share_class_figi_value,
-        mics=_merge_mics(group),
-        currency=_merge_currency(group),
-        last_price=_merge_decimal_field(group, "last_price"),
-        market_cap=_merge_decimal_field(group, "market_cap"),
-        fifty_two_week_min=_merge_decimal_field(group, "fifty_two_week_min"),
-        fifty_two_week_max=_merge_decimal_field(group, "fifty_two_week_max"),
-        dividend_yield=_merge_decimal_field(group, "dividend_yield"),
-        market_volume=_merge_decimal_field(group, "market_volume"),
-        held_insiders=_merge_decimal_field(group, "held_insiders"),
-        held_institutions=_merge_decimal_field(group, "held_institutions"),
-        short_interest=_merge_decimal_field(group, "short_interest"),
-        share_float=_merge_decimal_field(group, "share_float"),
-        shares_outstanding=_merge_decimal_field(group, "shares_outstanding"),
-        revenue_per_share=_merge_decimal_field(group, "revenue_per_share"),
-        profit_margin=_merge_decimal_field(group, "profit_margin"),
-        gross_margin=_merge_decimal_field(group, "gross_margin"),
-        operating_margin=_merge_decimal_field(group, "operating_margin"),
-        free_cash_flow=_merge_decimal_field(group, "free_cash_flow"),
-        operating_cash_flow=_merge_decimal_field(group, "operating_cash_flow"),
-        return_on_equity=_merge_decimal_field(group, "return_on_equity"),
-        return_on_assets=_merge_decimal_field(group, "return_on_assets"),
-        performance_1_year=_merge_decimal_field(group, "performance_1_year"),
-        total_debt=_merge_decimal_field(group, "total_debt"),
-        revenue=_merge_decimal_field(group, "revenue"),
-        ebitda=_merge_decimal_field(group, "ebitda"),
-        trailing_pe=_merge_decimal_field(group, "trailing_pe"),
-        price_to_book=_merge_decimal_field(group, "price_to_book"),
-        trailing_eps=_merge_decimal_field(group, "trailing_eps"),
-        analyst_rating=_merge_analyst_rating(group),
-        industry=_merge_industry(group),
-        sector=_merge_sector(group),
-    )
-
-
-def _validate_share_class_figi(group: Sequence[RawEquity]) -> str:
-    """
-    Validates that all RawEquity objects in the group share the same
-    share_class_figi value.
+    Retrieves the specified field from each RawEquity object in the group.
+    Optionally filters out None values from the result.
 
     Args:
-        group (Sequence[RawEquity]): A non-empty sequence of RawEquity objects to
-            validate.
-
-    Raises:
-        ValueError: If the group is empty or contains multiple distinct
-            share_class_figi values.
+        group (Sequence[RawEquity]): Sequence of RawEquity objects to extract from.
+        field (str): Name of the field to extract from each object.
+        filter_none (bool, optional): If True, exclude None values from the result.
+            Defaults to True.
 
     Returns:
-        str: The single shared share_class_figi value present in the group.
+        list: Extracted field values, optionally filtered to exclude None values.
     """
-    if not group:
-        raise ValueError("Cannot merge an empty group of equities")
-
-    figis = {raw_equity.share_class_figi for raw_equity in group}
-    if len(figis) != 1:
-        raise ValueError(
-            "All raw equities in the group must have identical share_class_figi values "
-            f"(found: {sorted(figis)})",
-        )
-    return figis.pop()
+    values = [getattr(eq, field) for eq in group]
+    return [v for v in values if v is not None] if filter_none else values
 
 
-def _merge_name(duplicate_group: Sequence[RawEquity], *, threshold: int = 90) -> str:
+class EquityIdentifiers(NamedTuple):
     """
-    Selects a representative equity name from a group of near-duplicate equities.
-
-    This function clusters similar equity names using fuzzy matching, then selects the
-    cluster with the highest total occurrence count. Within the chosen cluster, it
-    returns the earliest original spelling found in the input sequence.
-
-    Args:
-        duplicate_group (Sequence[RawEquity]): A sequence of RawEquity objects
-            considered near-duplicates, each with a 'name' attribute.
-        threshold (int, optional): Similarity threshold (0-100) for clustering names.
-            Defaults to 90.
-
-    Returns:
-        str: The selected representative equity name from the group.
+    Representative identifiers extracted from a group of RawEquity records.
+
+    Attributes:
+        symbol: Representative ticker symbol.
+        name: Representative equity name.
+        isin: Representative ISIN identifier.
+        cusip: Representative CUSIP identifier.
+        cik: Representative CIK identifier.
+        lei: Representative LEI identifier.
+        share_class_figi: Validated share class FIGI (must be identical across group).
     """
-    names = [equity.name for equity in duplicate_group]
-
-    # cluster names by fuzzy similarity
-    clusters = _cluster(names, threshold=threshold)
 
-    # weight clusters and keep earliest spelling
-    weight = Counter(names)  # how many times each form occurs
+    symbol: str
+    name: str
+    isin: str | None
+    cusip: str | None
+    cik: str | None
+    lei: str | None
+    share_class_figi: str
 
-    def _cluster_weight(cluster: list[str]) -> int:
-        return sum(weight[token] for token in cluster)
 
-    # choose cluster with the most occurrences (i.e. highest weight)
-    best_cluster = max(clusters, key=_cluster_weight)
-
-    return next(name for name in names if name in best_cluster)
-
-
-def _merge_symbol(duplicate_group: Sequence[RawEquity]) -> str:
+def merge(group: Sequence[RawEquity]) -> RawEquity:
     """
-    Selects the most frequently occurring symbol from a group of RawEquity objects.
+    Merge a group of RawEquity records into a single, representative RawEquity instance.
 
-    If multiple symbols share the highest frequency (a tie), the symbol that appears
-    first in the group is returned.
+    Each field is merged using a configurable strategy defined in FIELD_CONFIG:
+      - Most fields use one of: mode (most frequent), median (for numerics), fuzzy
+      clustering (for similar strings), or union (for lists).
+      - Price range fields (last_price, fifty_two_week_min, fifty_two_week_max) are
+      merged together with additional consistency checks.
+
+    The merging process ensures that all records in the group share the same
+    share_class_figi; otherwise, a ValueError is raised.
 
     Args:
-        duplicate_group (Sequence[RawEquity]): A sequence of RawEquity objects that are
-            considered duplicates and need to be merged based on their symbol.
+        group (Sequence[RawEquity]): Non-empty sequence of RawEquity objects to merge.
+        All must have identical share_class_figi.
 
     Returns:
-        str: The symbol that is the mode of the group, with ties broken by first
-            occurrence.
-    """
-    symbols = [equity.symbol for equity in duplicate_group]
-    return Counter(symbols).most_common(1)[0][0]
+        RawEquity: A new RawEquity instance with merged values for each field, according
+        to the configured strategies.
 
-
-def _merge_decimal_field(
-    duplicate_group: Sequence[RawEquity],
-    field: str,
-) -> Decimal | None:
+    Raises:
+        ValueError: If the group is empty or contains multiple distinct share_class_figi
+        values.
     """
-    Calculates the median value for a specified Decimal field from a group of
-    RawEquity objects, ignoring any entries where the field value is None.
+    share_class_figi = _validate_share_class_figi(group)
 
-    Args:
-        duplicate_group (Sequence[RawEquity]): A sequence of RawEquity instances,
-            each potentially containing the specified field.
-        field (str): The name of the Decimal field to merge.
+    merged = {
+        "share_class_figi": share_class_figi,
+        **{
+            field: _apply_strategy(group, field, spec)
+            for field, spec in FIELD_CONFIG.items()
+            if field not in PRICE_RANGE_FIELDS
+        },
+        **_merge_price_range(group),
+    }
 
-    Returns:
-        Decimal | None: The median of the non-null field values as a Decimal,
-            or None if no valid values are present.
-    """
-    values: list[Decimal] = [
-        getattr(equity, field)
-        for equity in duplicate_group
-        if getattr(equity, field) is not None
-    ]
-    return median(values) if values else None
+    return RawEquity.model_validate(merged)
 
 
-def _merge_id(duplicate_group: Sequence[RawEquity], field: str) -> str | None:
+def extract_identifiers(group: Sequence[RawEquity]) -> EquityIdentifiers:
     """
-    Selects the most frequent non-null value for a specified identifier field
-    ("isin", "cusip", "cik" or "share_class_figi") from a group of RawEquity objects.
+    Compute representative identifiers from a group of RawEquity records.
 
-    In case of a tie, returns the earliest occurrence in the original group order.
-    Returns None if all values are null.
+    Uses the same resolution algorithms as merge() — mode for IDs,
+    fuzzy clustering for name, frequency for symbol.
 
     Args:
-        duplicate_group (Sequence[RawEquity]): A sequence of RawEquity objects to merge.
-        field (str): The name of the identifier field to merge ("isin", "cusip", "cik"
-        or "share_class_figi").
+        group: A non-empty sequence of RawEquity objects from which to extract
+            identifiers. All records must share the same share_class_figi.
 
     Returns:
-        str | None: Most frequent non-null identifier value, or None if all are null.
-    """
-    # get the values for the given field
-    values = [
-        getattr(equity, field)
-        for equity in duplicate_group
-        if getattr(equity, field) is not None
-    ]
-
-    if not values:
-        return None
-
-    counts = Counter(values)
-
-    # max(counts.values()) guaranteed ≥ 1
-    best_freq = max(counts.values())
+        EquityIdentifiers: Representative identifiers resolved from the group.
 
-    # earliest among the non-null values with best frequency
-    return next(value for value in values if counts[value] == best_freq)
-
-
-def _merge_mics(duplicate_group: Sequence[RawEquity]) -> list[str] | None:
-    """
-    Merges all non-null MIC lists from a group of RawEquity objects, preserving the
-    order of first occurrence and removing duplicates.
-
-    Args:
-        duplicate_group (Sequence[RawEquity]): A sequence of RawEquity objects, each
-            possibly containing a list of MICs.
-
-    Returns:
-        list[str] | None: A list of unique MICs in order of first appearance, or None
-            if no MICs are found.
+    Raises:
+        ValueError: If the group is empty or contains multiple distinct
+            share_class_figi values.
     """
-    # combine all (possibly None) MIC lists
-    combined_mics = chain.from_iterable(e.mics or [] for e in duplicate_group)
-
-    # Keep only truthy, non-blank strings
-    cleaned = (mic for mic in combined_mics if mic and str(mic).strip())
-
-    # Order-preserving de-duplication
-    unique_mics = list(dict.fromkeys(cleaned))
-
-    return unique_mics or None
+    share_class_figi = _validate_share_class_figi(group)
+
+    return EquityIdentifiers(
+        symbol=mode_first(_extract_field(group, "symbol")),
+        name=fuzzy_cluster_mode(_extract_field(group, "name")),
+        isin=mode_first(_extract_field(group, "isin")),
+        cusip=mode_first(_extract_field(group, "cusip")),
+        cik=mode_first(_extract_field(group, "cik")),
+        lei=mode_first(_extract_field(group, "lei")),
+        share_class_figi=share_class_figi,
+    )
 
 
-def _merge_currency(duplicate_group: Sequence[RawEquity]) -> str | None:
+def _validate_share_class_figi(group: Sequence[RawEquity]) -> str:
     """
-    Selects the most frequent non-null currency code (ISO-4217) from a group of
-    duplicate RawEquity objects. In case of a tie, returns the first encountered
-    currency code in the original group order. If all currency codes are null,
-    returns None.
+    Validates that all RawEquity objects in the group share the same
+    share_class_figi value.
 
     Args:
-        duplicate_group (Sequence[RawEquity]): A sequence of RawEquity objects, each
-            possibly containing a currency attribute.
-
-    Returns:
-        str | None: The most frequent non-null currency code, or None if all are null.
-    """
-    # get the currency codes from the duplicate group
-    currency_codes = [
-        equity.currency for equity in duplicate_group if equity.currency is not None
-    ]
-
-    if not currency_codes:
-        return None
-
-    freq = Counter(currency_codes)
-    best_freq = max(freq.values())
-
-    # earliest among the non-null currencies with best frequency
-    return next(currency for currency in currency_codes if freq[currency] == best_freq)
-
-
-def _merge_analyst_rating(duplicate_group: Sequence[RawEquity]) -> str | None:
-    """
-    Selects the most frequent non-null analyst rating ("BUY", "SELL", or "HOLD")
-    from a group of RawEquity objects. If there is a tie, the rating that appears
-    first in the input sequence is returned. Returns None if all ratings are missing.
+        group (Sequence[RawEquity]): A non-empty sequence of RawEquity objects to
+            validate.
 
-    Args:
-        duplicate_group (Sequence[RawEquity]): A sequence of RawEquity objects,
-            each potentially containing an analyst_rating attribute.
+    Raises:
+        ValueError: If the group is empty or contains multiple distinct
+            share_class_figi values.
 
     Returns:
-        str | None: The most frequent non-null analyst rating, or None if all are
-            missing.
+        str: The single shared share_class_figi value present in the group.
     """
-    ratings = [
-        equity.analyst_rating
-        for equity in duplicate_group
-        if equity.analyst_rating is not None
-    ]
-
-    if not ratings:
-        return None
-
-    freq = Counter(ratings)
-    best = max(freq.values())
+    if not group:
+        raise ValueError("Cannot merge an empty group of equities")
 
-    # earliest among the non-null ratings with best frequency
-    return next(rating for rating in ratings if freq[rating] == best)
+    figis = {raw_equity.share_class_figi for raw_equity in group}
+    if len(figis) != 1:
+        raise ValueError(
+            "All raw equities in the group must have identical share_class_figi values "
+            f"(found: {sorted(figis)})",
+        )
+    return figis.pop()
 
 
-def _merge_industry(
-    duplicate_group: Sequence[RawEquity],
-    *,
-    threshold: int = 90,
-) -> str | None:
+def _apply_strategy(
+    group: Sequence[RawEquity],
+    field: str,
+    spec: FieldSpec,
+) -> object:
     """
-    Selects a representative industry from a group of RawEquity objects.
+    Apply a specific merge strategy to a field.
 
-    - Ignores blank or missing industry values.
-    - Clusters similar industry names with single-link fuzzy matching (token-set ratio).
-    - The cluster with the highest total frequency is chosen (majority rule).
-    - Within the winning cluster, the earliest spelling in the original sequence is
-        returned, preserving original capitalisation.
+    Extracts field values from the group and applies the configured strategy.
+    If fewer than min_sources non-None values exist, returns None to prevent
+    accepting dubious single-source data.
 
     Args:
-        duplicate_group (Sequence[RawEquity]): Sequence of RawEquity objects, each
-            possibly containing an industry attribute.
-        threshold (int, optional): Similarity threshold (0-100) for clustering
-            industry names. Defaults to 90.
+        group (Sequence[RawEquity]): Sequence of RawEquity objects to merge.
+        field (str): Name of the field to merge.
+        spec (FieldSpec): Strategy specification for this field.
 
     Returns:
-        str | None: The selected representative industry string, or None if all values
-            are missing or blank.
+        object: The merged value for this field, or None if quorum not met.
     """
-    # skip if every record is null or blank
-    industries = [
-        equity.industry for equity in duplicate_group if equity.industry is not None
-    ]
-
-    if not industries:
-        return None
-
-    # cluster names by fuzzy similarity
-    clusters = _cluster(industries, threshold=threshold)
+    values = _extract_field(group, field, filter_none=(spec.strategy != Strategy.UNION))
 
-    # weight clusters and keep earliest spelling
-    weight = Counter(industries)
+    if spec.max_deviation is not None and spec.strategy == Strategy.MEDIAN:
+        values = filter_by_deviation(values, spec.max_deviation)
 
-    def _cluster_weight(cluster: list[str]) -> int:
-        return sum(weight[token] for token in cluster)
+    if len(values) < spec.min_sources:
+        return None
 
-    # choose cluster with the most occurrences (i.e. highest weight)
-    best_cluster = max(clusters, key=_cluster_weight)
+    dispatch = {
+        Strategy.MODE: mode_first,
+        Strategy.FUZZY_CLUSTER: partial(fuzzy_cluster_mode, threshold=spec.threshold),
+        Strategy.UNION: union_ordered,
+        Strategy.MEDIAN: median_decimal,
+    }
 
-    # earliest spelling in original order among non-nulls
-    return next(industry for industry in industries if industry in best_cluster)
+    return dispatch[spec.strategy](values)
 
 
-def _merge_sector(
-    duplicate_group: Sequence[RawEquity],
-    *,
-    threshold: int = 90,
-) -> str | None:
+def _merge_price_range(
+    group: Sequence[RawEquity],
+    min_consistent: int = 2,
+) -> dict[str, Decimal | None]:
     """
-    Selects a representative sector from a group of RawEquity objects.
-
-    This function clusters similar sector names using fuzzy matching (token-set ratio,
-    single-link) and a configurable threshold. The cluster with the highest total
-    frequency is chosen. Within the winning cluster, the earliest spelling in the
-    original sequence is returned, preserving original capitalisation.
+    Merge last_price, fifty_two_week_min, and fifty_two_week_max with tiered quality
+    checks.
+
+    Attempts to merge price fields as a coherent triplet when possible, falling back to
+    independent field merging when complete records are unavailable. This preserves data
+    quality through consistency checks whilst avoiding unnecessary data loss.
+
+    Primary strategy (preferred):
+      - Requires records with all three price fields populated (complete records).
+      - Filters out records where last_price violates the 52-week range constraint.
+      - A 10% tolerance above fifty_two_week_max accommodates timing drift between
+        feeds.
+      - If quorum of consistent complete records is met (default: 2), returns median
+        values.
+
+    Fallback strategy (when quorum not met):
+      - Merges each price field independently using per-field configuration from
+        FIELD_CONFIG.
+      - Each field still requires its own min_sources threshold (typically 2).
+      - Allows partial price data when complete triplets are unavailable across sources.
 
     Args:
-        duplicate_group (Sequence[RawEquity]): Sequence of RawEquity records, each
-            possibly containing a sector attribute.
-        threshold (int, optional): Similarity threshold (0-100) for clustering sector
-            names. Defaults to 90.
+        group (Sequence[RawEquity]): Sequence of RawEquity objects to merge.
+        min_consistent (int): Minimum number of consistent complete records required
+            for primary strategy. Defaults to 2.
 
     Returns:
-        str | None: The selected representative sector string, or None if all values
-            are missing or blank.
+        dict[str, Decimal | None]: Dictionary containing merged last_price,
+            fifty_two_week_min, and fifty_two_week_max values. Fields may be None
+            if neither strategy can satisfy quorum requirements.
     """
-    # skip if every record is null or blank
-    sectors = [equity.sector for equity in duplicate_group if equity.sector is not None]
-
-    if not sectors:
-        return None
-
-    # cluster names by fuzzy similarity
-    clusters = _cluster(sectors, threshold=threshold)
-
-    # weight clusters and keep earliest spelling
-    weights = Counter(sectors)
-
-    def _cluster_weight(cluster: list[str]) -> int:
-        return sum(weights[token] for token in cluster)
+    consistent = tuple(
+        filter(_is_price_consistent, filter(_is_price_complete, group)),
+    )
 
-    # choose cluster with the most occurrences (i.e. highest weight)
-    best_cluster = max(clusters, key=_cluster_weight)
+    if len(consistent) >= min_consistent:
+        return {
+            "last_price": median_decimal([eq.last_price for eq in consistent]),
+            "fifty_two_week_min": median_decimal(
+                [eq.fifty_two_week_min for eq in consistent],
+            ),
+            "fifty_two_week_max": median_decimal(
+                [eq.fifty_two_week_max for eq in consistent],
+            ),
+        }
 
-    # earliest spelling in original order among non-nulls
-    return next(sector for sector in sectors if sector in best_cluster)
+    # Fallback: merge fields independently
+    return {
+        field: _apply_strategy(group, field, FIELD_CONFIG[field])
+        for field in PRICE_RANGE_FIELDS
+    }
 
 
-@cache
-def _token_ratio(a: str, b: str) -> int:
+def _is_price_complete(eq: RawEquity) -> bool:
     """
-    Compute the token-set ratio between two strings using fuzzy matching.
+    Checks if a RawEquity record has non-null values for last_price, fifty_two_week_min,
+    and fifty_two_week_max.
 
     Args:
-        a (str): The first string to compare.
-        b (str): The second string to compare.
+        eq (RawEquity): The RawEquity instance to check.
 
     Returns:
-        int: The token-set similarity ratio (0-100) between the two strings.
+        bool: True if all three price fields are not None, False otherwise.
     """
-    return fuzz.token_set_ratio(a, b)
+    return (
+        eq.last_price is not None
+        and eq.fifty_two_week_min is not None
+        and eq.fifty_two_week_max is not None
+    )
 
 
-def _cluster(names: list[str], threshold: int = 90) -> list[list[str]]:
+def _is_price_consistent(eq: RawEquity) -> bool:
     """
-    Groups similar strings into clusters using single-link clustering based on token-set
-    ratio.
-
-    Each name is compared to the representative (first item) of each existing cluster.
-    If the token-set ratio between the name and a cluster's representative is greater
-    than or equal to the specified threshold, the name is added to that cluster.
-
-    Otherwise, a new cluster is created for the name.
+    Checks if the last_price of a RawEquity record falls within its fifty_two_week_min
+    and fifty_two_week_max range, allowing a 10% tolerance above the max.
 
     Args:
-        names (list[str]): List of strings to be clustered.
-        threshold (int, optional): Minimum token-set ratio (0-100) required to join an
-            existing cluster. Defaults to 90.
+        eq (RawEquity): The RawEquity instance to check.
 
     Returns:
-        list[list[str]]: A list of clusters, where each cluster is a list of similar
-            strings.
+        bool: True if last_price is between fifty_two_week_min and up to 10% above
+              fifty_two_week_max, False otherwise. Returns False if any price field
+              is None.
     """
-    clusters: list[list[str]] = []
-
-    for name in names:
-        # find the first cluster whose representative (first item)
-        # is similar enough to this name
-        target: list[str] = next(
-            (
-                cluster
-                for cluster in clusters
-                if _token_ratio(name, cluster[0]) >= threshold
-            ),
-            None,
-        )
-
-        if target:
-            target.append(name)
-        else:
-            clusters.append([name])
-
-    return clusters
+    if (
+        eq.last_price is None
+        or eq.fifty_two_week_min is None
+        or eq.fifty_two_week_max is None
+    ):
+        return False
+
+    price_tolerance = Decimal("1.1")
+    return (
+        eq.fifty_two_week_min
+        <= eq.last_price
+        <= eq.fifty_two_week_max * price_tolerance
+    )