marketmyna 0.2.0__py3-none-any.whl

marketmyna/services/shariah.py

@@ -0,0 +1,246 @@
+"""Full Shariah screen for one stock: business activity + financial ratios.
+
+Methodology (the common ground of the major Islamic index providers):
+
+* Business screen - the core business must not be interest-based finance,
+  insurance, alcohol, tobacco, pork, gambling, adult entertainment or
+  weapons. Mixed businesses (hotels, media, REITs) are flagged doubtful.
+* Financial screens - S&P / Dow Jones Islamic style, the basis of the
+  Nifty / BSE Shariah indices that Indian "Ethical" funds track:
+      interest-bearing debt          < 33% of 36-month average market cap
+      cash + interest-bearing assets < 33% of 36-month average market cap
+      receivables + cash             < 49% of 36-month average market cap
+  AAOIFI uses a stricter 30% for the first two; a stock between 30% and
+  33% passes S&P but not AAOIFI and is reported as doubtful.
+* Non-permissible income - interest income must stay under 5% of revenue.
+  That share of any dividend (or gain) should be given to charity
+  ("purification").
+
+Market cap falls back to total assets (MSCI / FTSE style) when Yahoo has
+no price history. Everything comes from Yahoo Finance and is best-effort:
+this is a screening aid, not a fatwa.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Optional
+
+from marketmyna.data.shariah import DOUBTFUL, HALAL, HARAM, UNKNOWN, business_status, screen_row
+
+from .financials import BALANCE_ROWS, _div, _extract, _num, _periods
+
+logger = logging.getLogger(__name__)
+
+LIMIT_DEBT = 33.0
+LIMIT_CASH = 33.0
+LIMIT_RECEIVABLES = 49.0
+LIMIT_AAOIFI = 30.0
+LIMIT_INTEREST_INCOME = 5.0
+
+_INTEREST_INCOME_ROWS = [("interest_income", "Interest income", ["Interest Income Non Operating", "Interest Income"])]
+_REVENUE_ROWS = [("revenue", "Total revenue", ["Total Revenue", "Operating Revenue"])]
+
+_TTL = 6 * 3600
+_cache: dict[tuple[str, str], tuple[float, dict]] = {}
+_lock = threading.Lock()
+
+VERDICT_LABELS = {
+    HALAL: "Ethical",
+    DOUBTFUL: "Doubtful",
+    HARAM: "Not ethical",
+    UNKNOWN: "Not enough data",
+}
+
+
+def _check(key: str, label: str, value: Optional[float], limit: float, basis: str, strict: Optional[float] = None) -> dict:
+    """One ratio test. status: pass | fail | borderline (passes S&P, fails AAOIFI) | unknown."""
+    if value is None:
+        status = "unknown"
+    elif value >= limit:
+        status = "fail"
+    elif strict is not None and value >= strict:
+        status = "borderline"
+    else:
+        status = "pass"
+    return {"key": key, "label": label, "value": value, "limit": limit, "strict_limit": strict, "basis": basis, "status": status}
+
+
+def _avg_market_cap(ticker, info: dict) -> tuple[Optional[float], str]:
+    """36-month average market cap in the reporting currency.
+
+    Scales today's market cap by (average monthly close / last close), so
+    share-class and ADR ratios stay right, then converts from the trading
+    currency to the currency the statements are published in."""
+    mcap = _num(info.get("marketCap"))
+    if not mcap:
+        return None, ""
+    basis = "current market cap"
+    try:
+        hist = ticker.history(period="3y", interval="1mo")
+        closes = hist["Close"].dropna() if hist is not None and not hist.empty else None
+        if closes is not None and len(closes) >= 6 and closes.iloc[-1] > 0:
+            mcap = mcap * float(closes.mean()) / float(closes.iloc[-1])
+            basis = f"{len(closes)}-month average market cap"
+    except Exception as exc:
+        logger.info("Shariah: price history failed: %s", exc)
+
+    trade_ccy = info.get("currency")
+    fin_ccy = info.get("financialCurrency")
+    if trade_ccy and fin_ccy and trade_ccy != fin_ccy:
+        import yfinance as yf
+
+        from ..data import ecb_fx
+
+        pair = f"{trade_ccy}{fin_ccy}=X"
+        try:
+            fx = ecb_fx.guarded(lambda: {pair: yf.Ticker(pair).history(period="5d")["Close"].dropna()},
+                                [pair], days=14)[pair]
+            mcap = mcap * float(fx.iloc[-1])
+            basis += f" (converted {trade_ccy}→{fin_ccy})"
+        except Exception as exc:
+            logger.info("Shariah: FX %s->%s failed: %s", trade_ccy, fin_ccy, exc)
+            return None, ""
+    return mcap, basis
+
+
+def _latest(values: list[Optional[float]]) -> Optional[float]:
+    return next((v for v in values if v is not None), None)
+
+
+def _pct(a: Optional[float], b: Optional[float]) -> Optional[float]:
+    r = _div(a, b)
+    return round(r * 100, 2) if r is not None else None
+
+
+def build_shariah_profile(symbol: str, market: str) -> dict:
+    key = (symbol.upper(), market)
+    with _lock:
+        hit = _cache.get(key)
+        if hit and time.time() - hit[0] < _TTL:
+            return hit[1]
+    data = _build(symbol, market)
+    with _lock:
+        _cache[key] = (time.time(), data)
+    return data
+
+
+def _build(symbol: str, market: str) -> dict:
+    import yfinance as yf
+
+    from .analysis_run import yahoo_symbol
+
+    if market == "crypto":
+        raise ValueError("The ethical screen does not cover crypto")
+
+    ticker = yf.Ticker(yahoo_symbol(symbol, market))
+    info: dict = {}
+    try:
+        info = ticker.info or {}
+    except Exception as exc:
+        logger.info("Shariah info for %s failed: %s", symbol, exc)
+    name = info.get("longName") or info.get("shortName") or symbol
+    base = {
+        "symbol": symbol,
+        "market": market,
+        "name": name,
+        "sector": info.get("sector"),
+        "industry": info.get("industry"),
+        "currency": info.get("financialCurrency") or info.get("currency"),
+        "source": "Company financial statements (market data feed)",
+    }
+
+    # Funds: the mandate decides, not balance-sheet ratios.
+    if info.get("quoteType") in ("ETF", "MUTUALFUND"):
+        status, reason = screen_row({"symbol": symbol, "name": name, "market": market, "type": "etf"})
+        return {
+            **base,
+            "kind": "fund",
+            "verdict": status,
+            "verdict_label": VERDICT_LABELS[status],
+            "business": {"status": status, "reason": reason, "flags": []},
+            "checks": [],
+            "purification_pct": None,
+            "reasons": [reason],
+        }
+
+    bal_df = ticker.balance_sheet
+    inc_df = ticker.income_stmt
+    periods = _periods(bal_df, inc_df)
+    if not info.get("sector") and not info.get("marketCap") and not periods:
+        # Yahoo throttles or has no coverage - fail rather than cache an empty screen.
+        raise RuntimeError(f"No financial data for {symbol} right now - try again shortly")
+
+    b_status, b_reason, flags = business_status(name, info.get("sector"), info.get("industry"), info.get("longBusinessSummary") or "")
+
+    bal = _extract(bal_df, BALANCE_ROWS, periods) if periods else {}
+    inc = _extract(inc_df, _INTEREST_INCOME_ROWS + _REVENUE_ROWS, periods) if periods else {}
+
+    debt = _latest(bal.get("total_debt", []))
+    cash = _latest(bal.get("cash", []))
+    receivables = _latest(bal.get("receivables", []))
+    assets = _latest(bal.get("total_assets", []))
+    revenue = _latest(inc.get("revenue", []))
+    interest_income = _latest(inc.get("interest_income", []))
+    if debt is None and assets is not None and bal_df is not None and not bal_df.empty and "Total Debt" not in bal_df.index:
+        debt = 0.0  # No debt line at all means no borrowings were reported.
+
+    mcap, basis = _avg_market_cap(ticker, info)
+    denom = mcap
+    if not denom:
+        denom, basis = assets, "total assets"
+
+    recv_cash = receivables + cash if receivables is not None and cash is not None else None
+    checks = [
+        _check("debt", "Interest-bearing debt", _pct(debt, denom), LIMIT_DEBT, basis, LIMIT_AAOIFI),
+        _check("cash", "Cash & interest-bearing securities", _pct(cash, denom), LIMIT_CASH, basis, LIMIT_AAOIFI),
+        _check("receivables", "Receivables + cash", _pct(recv_cash, denom), LIMIT_RECEIVABLES, basis),
+        _check("interest_income", "Interest income", _pct(interest_income, revenue), LIMIT_INTEREST_INCOME, "revenue"),
+    ]
+    if revenue and interest_income is None:
+        # Yahoo omits the line for many companies; treat as not reported rather than failing the stock.
+        checks[-1]["note"] = "Not reported separately - read the annual report's 'other income' note"
+
+    reasons: list[str] = []
+    if b_status == HARAM:
+        verdict = HARAM
+        reasons.append(b_reason)
+    else:
+        failed = [c for c in checks if c["status"] == "fail"]
+        borderline = [c for c in checks if c["status"] == "borderline"]
+        missing = [c for c in checks[:2] if c["status"] == "unknown"]
+        for c in failed:
+            reasons.append(f"{c['label']} is {c['value']:.1f}% of {c['basis']} (limit {c['limit']:.0f}%)")
+        for c in borderline:
+            reasons.append(f"{c['label']} is {c['value']:.1f}% - within the standard {c['limit']:.0f}% limit but above the stricter {c['strict_limit']:.0f}%")
+        if b_status in (DOUBTFUL, UNKNOWN):
+            reasons.append(b_reason)
+        if missing:
+            reasons.append("Missing balance-sheet data: " + ", ".join(c["label"].lower() for c in missing))
+        if failed:
+            verdict = HARAM
+        elif borderline or b_status == DOUBTFUL:
+            verdict = DOUBTFUL
+        elif missing or b_status == UNKNOWN:
+            verdict = UNKNOWN if len(missing) == 2 else DOUBTFUL
+        else:
+            verdict = HALAL
+            reasons.append(b_reason)
+            reasons.append("Debt, cash and receivables are all within the standard and the stricter limits")
+
+    # Purification only applies to a stock one may hold.
+    purification = _pct(interest_income, revenue) if verdict != HARAM else None
+    return {
+        **base,
+        "kind": "stock",
+        "verdict": verdict,
+        "verdict_label": VERDICT_LABELS[verdict],
+        "business": {"status": b_status, "reason": b_reason, "flags": flags},
+        "checks": checks,
+        "market_cap_basis": basis or None,
+        "period": str(periods[0])[:10] if periods else None,
+        "purification_pct": purification,
+        "reasons": reasons,
+    }

marketmyna/services/sip.py

@@ -0,0 +1,148 @@
+"""SIP backtest on a fund's real NAV history, plus a step-up projection.
+
+Answers three questions for one scheme: what would a monthly SIP over the last
+N years be worth today, would a lumpsum of the same total have done better, and
+does the SIP day of the month matter. Pure functions over a NAV series so they
+test offline; the step-up maths reuses SIPOptimizer (marketmyna/analysis/sip_optimizer.py).
+"""
+
+from __future__ import annotations
+
+from datetime import date
+
+import pandas as pd
+
+SIP_DAYS = (1, 5, 10, 15, 20, 25)
+
+
+def xirr(flows: list[tuple[date, float]]) -> float | None:
+    """Annualised internal rate of return for dated cash flows (bisection)."""
+    if len(flows) < 2 or not any(v > 0 for _, v in flows) or not any(v < 0 for _, v in flows):
+        return None
+    t0 = flows[0][0]
+
+    def npv(rate: float) -> float:
+        return sum(v / (1 + rate) ** ((d - t0).days / 365.0) for d, v in flows)
+
+    lo, hi = -0.99, 10.0
+    if npv(lo) * npv(hi) > 0:
+        return None
+    for _ in range(200):
+        mid = (lo + hi) / 2
+        if npv(lo) * npv(mid) <= 0:
+            hi = mid
+        else:
+            lo = mid
+    return (lo + hi) / 2
+
+
+def _buy_dates(nav: pd.Series, start: pd.Timestamp, day: int) -> list[pd.Timestamp]:
+    """First NAV date on or after `day` of each month from `start` (next trading day)."""
+    out: list[pd.Timestamp] = []
+    month = pd.Timestamp(start.year, start.month, 1)
+    end = nav.index[-1]
+    while month <= end:
+        target = month + pd.Timedelta(days=day - 1)
+        pos = nav.index.searchsorted(target)
+        if pos < len(nav) and nav.index[pos] >= start and (nav.index[pos].year, nav.index[pos].month) == (target.year, target.month):
+            out.append(nav.index[pos])
+        month += pd.offsets.MonthBegin(1)
+    return out
+
+
+def simulate(nav: pd.Series, monthly: float, start: pd.Timestamp, day: int) -> dict | None:
+    """Monthly SIP of `monthly` from `start` on `day`, valued at the last NAV."""
+    dates = _buy_dates(nav, start, day)
+    if len(dates) < 2:
+        return None
+    units = sum(monthly / float(nav[d]) for d in dates)
+    invested = monthly * len(dates)
+    last_date, last_nav = nav.index[-1], float(nav.iloc[-1])
+    value = units * last_nav
+    flows = [(d.date(), -monthly) for d in dates] + [(last_date.date(), value)]
+    return {
+        "day": day,
+        "installments": len(dates),
+        "invested": invested,
+        "units": units,
+        "avg_cost": invested / units,
+        "value": value,
+        "gain_pct": (value / invested - 1) * 100,
+        "xirr_pct": _pct(xirr(flows)),
+    }
+
+
+def backtest(nav: pd.Series, monthly: float, years: int, day: int) -> dict:
+    """SIP vs lumpsum vs SIP day, over the last `years` of NAV history."""
+    nav = nav.dropna().sort_index()
+    if len(nav) < 30:
+        return {"error": "Not enough NAV history"}
+    end = nav.index[-1]
+    start = max(end - pd.DateOffset(years=years), nav.index[0])
+    note = None
+    if start > end - pd.DateOffset(years=years) + pd.Timedelta(days=31):
+        note = f"Fund history starts {nav.index[0].date()}, so the backtest is shorter than {years} years."
+
+    sip = simulate(nav, monthly, start, day)
+    if sip is None:
+        return {"error": "Not enough NAV history"}
+
+    first = _buy_dates(nav, start, day)[0]
+    lump_nav = float(nav[first])
+    lump_value = sip["invested"] / lump_nav * float(nav.iloc[-1])
+    span = (end - first).days / 365.0
+    lump = {
+        "date": str(first.date()),
+        "invested": sip["invested"],
+        "value": lump_value,
+        "gain_pct": (lump_value / sip["invested"] - 1) * 100,
+        "cagr_pct": ((lump_value / sip["invested"]) ** (1 / span) - 1) * 100 if span > 0 else None,
+    }
+
+    # Rank days by XIRR, not end value: a later day can buy one instalment fewer
+    by_day = [r for d in SIP_DAYS if (r := simulate(nav, monthly, start, d))]
+    ranked = [r for r in by_day if r["xirr_pct"] is not None]
+    spread = None
+    if ranked:
+        best = max(ranked, key=lambda r: r["xirr_pct"])
+        worst = min(ranked, key=lambda r: r["xirr_pct"])
+        spread = {"best_day": best["day"], "worst_day": worst["day"],
+                  "diff_pts": best["xirr_pct"] - worst["xirr_pct"]}
+
+    return {
+        "start": str(start.date()),
+        "end": str(end.date()),
+        "monthly": monthly,
+        "sip": sip,
+        "lumpsum": lump,
+        "winner": "sip" if sip["value"] >= lump_value else "lumpsum",
+        "by_day": by_day,
+        "day_spread": spread,
+        "note": note,
+    }
+
+
+def step_up(monthly: float, step_pct: float, years: int, expected_pct: float) -> dict:
+    """Projected corpus for a SIP that rises `step_pct` each year, vs a flat SIP."""
+    from marketmyna.analysis.sip_optimizer import SIPOptimizer
+
+    opt = SIPOptimizer(data_fetcher=object())  # projections need no data
+    stepped = opt.calculate_step_up_sip(monthly, step_pct, years, expected_pct)
+    flat = opt.calculate_step_up_sip(monthly, 0, years, expected_pct)
+    return {
+        "monthly": monthly,
+        "step_pct": step_pct,
+        "years": years,
+        "expected_pct": expected_pct,
+        "invested": stepped.total_invested,
+        "corpus": stepped.projected_corpus,
+        "flat_invested": flat.total_invested,
+        "flat_corpus": flat.projected_corpus,
+        "yearly": [{"year": y["year"], "monthly_sip": y["monthly_sip"], "corpus": y["year_end_corpus"],
+                    "flat_corpus": f["year_end_corpus"]}
+                   for y, f in zip(stepped.yearly_breakdown, flat.yearly_breakdown)],
+    }
+
+
+def _pct(v: float | None) -> float | None:
+    return None if v is None else v * 100