Download src/fundamentals.py from s-ttp/vitals: direct link, hf CLI and curl.
- Browser
- Download file 34.3 kB
-
https://huggingface.co/spaces/s-ttp/vitals/resolve/main/src/fundamentals.py
- Command line
-
hf download hf://spaces/s-ttp/vitals/src/fundamentals.py
-
curl -L -o fundamentals.py https://huggingface.co/spaces/s-ttp/vitals/resolve/main/src/fundamentals.py
34.3 kB
| """US deep fundamentals β the practitioner toolkit on Sharadar history + Alpha Vantage estimates. | |
| Everything here is DETERMINISTIC arithmetic on audited statements, so the committee argues | |
| from numbers rather than adjectives: | |
| β’ forensic quality β Piotroski F-score, Altman Z, Beneish M-score, Sloan accruals, cash conversion | |
| β’ Buffett / Greenblatt economics β owner earnings, FCF yield, ROIC and 5-year incremental ROIC, | |
| EBIT/EV earnings yield, Graham number, Lynch PEG and category | |
| β’ capital allocation β buyback yield vs dilution, stock-based comp share, FCF payout, dividend streak | |
| β’ valuation vs the company's own 10-year history (Sharadar DAILY) | |
| β’ earnings momentum β surprise history, estimate revisions (Alpha Vantage) | |
| β’ ownership β open-market insider flow (SF2), 13F holder / share changes (SF3A) | |
| β’ sell discipline β thesis-break triggers derived from the same numbers | |
| Only plain US listings (no exchange suffix) are eligible; everything degrades to "n/a". | |
| """ | |
| from __future__ import annotations | |
| import concurrent.futures as cf | |
| import hashlib | |
| import json | |
| import math | |
| import os | |
| import ssl | |
| import urllib.parse | |
| import urllib.request | |
| from datetime import date, timedelta | |
| import certifi | |
| from .market_data import _av_call, _cache_get, _cache_put, NDL_KEY, analyst_view | |
| CTX = ssl.create_default_context(cafile=certifi.where()) | |
| CYCLICAL = {"Energy", "Basic Materials", "Industrials", "Consumer Cyclical", "Financial Services", "Real Estate"} | |
| SOFTWARE_HINT = ("software", "internet", "semiconductor", "information technology", "application") | |
| def _f(x): | |
| try: | |
| v = float(x) | |
| return v if math.isfinite(v) else None | |
| except (TypeError, ValueError): | |
| return None | |
| def _ndl_key(table: str, params: dict) -> str: | |
| return "ndl_" + hashlib.md5((table + json.dumps(params, sort_keys=True)).encode()).hexdigest()[:16] | |
| def _sf1_params(t: str, dim: str = "ARY") -> dict: | |
| return {"ticker": t, "dimension": dim, "qopts.columns": _SF1, "qopts.per_page": 40} | |
| def _daily_params(t: str) -> dict: | |
| start = (date.today() - timedelta(days=3652)).isoformat() | |
| return {"ticker": t, "date.gte": start, "qopts.columns": "date,pe,evebitda,ps,pb", "qopts.per_page": 10000} | |
| def _sf2_params(t: str, months: int = 6) -> dict: | |
| since = (date.today() - timedelta(days=30 * months)).isoformat() | |
| return {"ticker": t, "filingdate.gte": since, "qopts.per_page": 500} | |
| def _sf3a_params(t: str) -> dict: | |
| return {"ticker": t, "qopts.per_page": 8} | |
| def prefetch_batch(tickers: list[str]) -> None: | |
| """One batched Sharadar call per table for MANY tickers, written into the same per-ticker | |
| cache keys the single-name fetchers use β a 47-name book then costs ~15 calls instead of | |
| ~200. Anything that fails simply leaves the per-name path to fetch on demand.""" | |
| if not NDL_KEY: | |
| return | |
| want = [t.upper() for t in tickers if "." not in t] | |
| todo = [t for t in want if _cache_get(_ndl_key("SHARADAR/SF1", _sf1_params(t))) is None] | |
| if not todo: | |
| return | |
| def grab(table: str, group: list[str], params: dict, per_ticker_params, key_col: str = "ticker"): | |
| try: | |
| url = (f"https://data.nasdaq.com/api/v3/datatables/{table}.json?" | |
| + urllib.parse.urlencode({**params, "ticker": ",".join(group), "api_key": NDL_KEY})) | |
| with urllib.request.urlopen(url, timeout=40, context=CTX) as r: | |
| dt = json.loads(r.read()).get("datatable") or {} | |
| cols = [c["name"] for c in dt.get("columns", [])] | |
| rows = [dict(zip(cols, r)) for r in dt.get("data", [])] | |
| except Exception: | |
| return | |
| by: dict[str, list] = {t: [] for t in group} | |
| for r in rows: | |
| by.setdefault(str(r.get(key_col) or "").upper(), []).append(r) | |
| for t in group: | |
| _cache_put(_ndl_key(table, per_ticker_params(t)), {"rows": by.get(t, [])}) | |
| jobs = [] | |
| for i in range(0, len(todo), 20): # SF1 annual: ~11 rows per ticker β 20 per call | |
| g = todo[i:i + 20] | |
| jobs.append(("SHARADAR/SF1", g, {"dimension": "ARY", "qopts.columns": _SF1, "qopts.per_page": 10000}, _sf1_params)) | |
| jobs.append(("SHARADAR/SF3A", g, {"qopts.per_page": 10000}, _sf3a_params)) | |
| jobs.append(("SHARADAR/SF2", g, {"filingdate.gte": _sf2_params("X")["filingdate.gte"], "qopts.per_page": 10000}, _sf2_params)) | |
| for i in range(0, len(todo), 4): # DAILY 10y: ~2,500 rows per ticker β 4 per call | |
| g = todo[i:i + 4] | |
| jobs.append(("SHARADAR/DAILY", g, {"date.gte": _daily_params("X")["date.gte"], | |
| "qopts.columns": "ticker,date,pe,evebitda,ps,pb", "qopts.per_page": 10000}, _daily_params)) | |
| with cf.ThreadPoolExecutor(max_workers=6) as ex: | |
| list(ex.map(lambda j: grab(*j), jobs)) | |
| def _ndl(table: str, params: dict, ttl_h: float = 24.0) -> list[dict]: | |
| """Sharadar datatable rows as dicts; cached by query.""" | |
| if not NDL_KEY: | |
| return [] | |
| key = _ndl_key(table, params) | |
| c = _cache_get(key) | |
| if c is not None: | |
| return c.get("rows", []) | |
| url = (f"https://data.nasdaq.com/api/v3/datatables/{table}.json?" | |
| + urllib.parse.urlencode({**params, "api_key": NDL_KEY})) | |
| try: | |
| with urllib.request.urlopen(url, timeout=30, context=CTX) as r: | |
| dt = json.loads(r.read()).get("datatable") or {} | |
| cols = [c["name"] for c in dt.get("columns", [])] | |
| rows = [dict(zip(cols, r)) for r in dt.get("data", [])] | |
| except Exception: | |
| return [] | |
| _cache_put(key, {"rows": rows}) | |
| return rows | |
| _SF1 = ("ticker,datekey,calendardate,revenue,gp,opinc,ebit,ebitda,netinc,ncfo,capex,fcf,sbcomp,dps," | |
| "payoutratio,roic,currentratio,de,ev,evebit,assets,assetsc,liabilities,liabilitiesc,debt,cashneq," | |
| "receivables,ppnenet,depamor,sgna,retearn,intexp,taxexp,ebt,sharesbas,shareswa,workingcapital," | |
| "invcap,tangibles,marketcap,eps,epsdil,bvps,pe,pb,ps,evebitda,roe,grossmargin,netmargin") | |
| def sf1_annual(t: str, n: int = 11) -> list[dict]: | |
| rows = _ndl("SHARADAR/SF1", _sf1_params(t)) | |
| rows.sort(key=lambda r: str(r.get("datekey")), reverse=True) | |
| return rows[:n] | |
| def sf1_quarterly(t: str, n: int = 12) -> list[dict]: | |
| rows = _ndl("SHARADAR/SF1", {"ticker": t, "dimension": "ARQ", "qopts.columns": _SF1, "qopts.per_page": 40}) | |
| rows.sort(key=lambda r: str(r.get("datekey")), reverse=True) | |
| return rows[:n] | |
| # ---------------- forensic scores ---------------- | |
| def piotroski(a: list[dict]) -> dict | None: | |
| """9-point F-score on the last two fiscal years (profitability, leverage/liquidity, efficiency).""" | |
| if len(a) < 2: | |
| return None | |
| c, p = a[0], a[1] | |
| ta, tap = _f(c.get("assets")), _f(p.get("assets")) | |
| if not ta or not tap: | |
| return None | |
| ni, cfo = _f(c.get("netinc")) or 0.0, _f(c.get("ncfo")) or 0.0 | |
| roa, roap = ni / ta, (_f(p.get("netinc")) or 0.0) / tap | |
| pts, why = 0, [] | |
| def hit(cond, label): | |
| nonlocal pts | |
| if cond: | |
| pts += 1 | |
| why.append(label) | |
| hit(roa > 0, "ROA>0"); hit(cfo > 0, "CFO>0"); hit(roa > roap, "ROAβ"); hit(cfo > ni, "CFO>NI") | |
| lev, levp = (_f(c.get("debt")) or 0.0) / ta, (_f(p.get("debt")) or 0.0) / tap | |
| hit(lev < levp, "leverageβ") | |
| cr, crp = _f(c.get("currentratio")), _f(p.get("currentratio")) | |
| hit(cr is not None and crp is not None and cr > crp, "liquidityβ") | |
| sh, shp = _f(c.get("sharesbas")), _f(p.get("sharesbas")) | |
| hit(sh is not None and shp is not None and sh <= shp * 1.005, "no dilution") | |
| gm, gmp = _f(c.get("grossmargin")), _f(p.get("grossmargin")) | |
| hit(gm is not None and gmp is not None and gm > gmp, "gross marginβ") | |
| at, atp = (_f(c.get("revenue")) or 0.0) / ta, (_f(p.get("revenue")) or 0.0) / tap | |
| hit(at > atp, "asset turnoverβ") | |
| return {"score": pts, "signals": why} | |
| def altman_z(c: dict, mcap: float | None) -> float | None: | |
| """Classic public-company Z (1968). Not meaningful for banks/insurers β caller masks financials.""" | |
| ta, tl = _f(c.get("assets")), _f(c.get("liabilities")) | |
| if not ta or not tl: | |
| return None | |
| wc = _f(c.get("workingcapital")) or ((_f(c.get("assetsc")) or 0.0) - (_f(c.get("liabilitiesc")) or 0.0)) | |
| re, ebit, rev = _f(c.get("retearn")) or 0.0, _f(c.get("ebit")) or 0.0, _f(c.get("revenue")) or 0.0 | |
| mc = mcap or _f(c.get("marketcap")) or 0.0 | |
| z = 1.2 * wc / ta + 1.4 * re / ta + 3.3 * ebit / ta + 0.6 * mc / tl + 1.0 * rev / ta | |
| return round(min(z, 30.0), 2) # 30+ is "irrelevantly safe" | |
| def beneish_m(a: list[dict]) -> float | None: | |
| """8-variable M-score; > β1.78 flags likely earnings manipulation.""" | |
| if len(a) < 2: | |
| return None | |
| c, p = a[0], a[1] | |
| g = lambda r, k: _f(r.get(k)) | |
| try: | |
| rev, revp = g(c, "revenue"), g(p, "revenue") | |
| rec, recp = g(c, "receivables"), g(p, "receivables") | |
| gp_, gpp = g(c, "gp"), g(p, "gp") | |
| ta, tap = g(c, "assets"), g(p, "assets") | |
| ac, acp = g(c, "assetsc"), g(p, "assetsc") | |
| pp, ppp = g(c, "ppnenet"), g(p, "ppnenet") | |
| da, dap = g(c, "depamor"), g(p, "depamor") | |
| sg, sgp = g(c, "sgna"), g(p, "sgna") | |
| tl, tlp = g(c, "liabilities"), g(p, "liabilities") | |
| ni, cfo = g(c, "netinc"), g(c, "ncfo") | |
| if None in (rev, revp, ta, tap, ni, cfo) or not rev or not revp or not ta or not tap: | |
| return None | |
| dsri = ((rec or 0) / rev) / (((recp or 0) / revp) or 1e-9) if recp else 1.0 | |
| gmi = (gpp / revp) / ((gp_ / rev) or 1e-9) if gp_ and gpp else 1.0 | |
| aqi = (1 - ((ac or 0) + (pp or 0)) / ta) / ((1 - ((acp or 0) + (ppp or 0)) / tap) or 1e-9) | |
| sgi = rev / revp | |
| depi = ((dap or 0) / ((dap or 0) + (ppp or 0) or 1e-9)) / (((da or 0) / ((da or 0) + (pp or 0) or 1e-9)) or 1e-9) if da and dap else 1.0 | |
| sgai = ((sg or 0) / rev) / (((sgp or 0) / revp) or 1e-9) if sg and sgp else 1.0 | |
| lvgi = ((tl or 0) / ta) / (((tlp or 0) / tap) or 1e-9) | |
| tata = (ni - cfo) / ta | |
| m = (-4.84 + 0.92 * dsri + 0.528 * gmi + 0.404 * aqi + 0.892 * sgi + 0.115 * depi | |
| - 0.172 * sgai + 4.679 * tata - 0.327 * lvgi) | |
| return round(m, 2) if math.isfinite(m) else None | |
| except ZeroDivisionError: | |
| return None | |
| # ---------------- economics & capital allocation ---------------- | |
| def _tax_rate(c: dict) -> float: | |
| te, ebt = _f(c.get("taxexp")), _f(c.get("ebt")) | |
| if te is not None and ebt and ebt > 0: | |
| return min(max(te / ebt, 0.0), 0.35) | |
| return 0.21 | |
| def economics(a: list[dict], price: float | None, mcap: float | None, sector: str, industry: str) -> dict: | |
| out: dict = {} | |
| if not a: | |
| return out | |
| c = a[0] | |
| ni, cfo, capex, fcf = _f(c.get("netinc")), _f(c.get("ncfo")), _f(c.get("capex")), _f(c.get("fcf")) | |
| da, rev, sh = _f(c.get("depamor")), _f(c.get("revenue")), _f(c.get("sharesbas")) | |
| mc = mcap or _f(c.get("marketcap")) | |
| ta = _f(c.get("assets")) | |
| if ni is not None and cfo is not None and ta: | |
| out["accruals"] = round((ni - cfo) / ta, 3) # Sloan: > 0.10 is a red flag | |
| if ni and fcf is not None: | |
| out["cash_conversion"] = round(fcf / ni, 2) if ni > 0 else None # FCF / net income | |
| if ni is not None and da is not None and capex is not None and sh: | |
| oe = ni + da - abs(capex) # Buffett owner earnings (full capex) | |
| out["owner_earnings_ps"] = round(oe / sh, 2) | |
| if price: | |
| out["owner_earnings_yield"] = round(oe / sh / price, 4) | |
| if fcf is not None and mc: | |
| out["fcf_yield"] = round(fcf / mc, 4) | |
| ebit, ev = _f(c.get("ebit")), _f(c.get("ev")) | |
| if ebit is not None and ev and ev > 0: | |
| out["greenblatt_ey"] = round(ebit / ev, 4) # EBIT / EV | |
| out["roic"] = _f(c.get("roic")) | |
| # 5-year incremental ROIC: Ξ NOPAT / Ξ invested capital | |
| if len(a) >= 6: | |
| p = a[5] | |
| nopat_c = (_f(c.get("ebit")) or 0.0) * (1 - _tax_rate(c)) | |
| nopat_p = (_f(p.get("ebit")) or 0.0) * (1 - _tax_rate(p)) | |
| ic_c, ic_p = _f(c.get("invcap")), _f(p.get("invcap")) | |
| if ic_c and ic_p and ic_c > 0 and ic_p > 0 and (ic_c - ic_p) > 0.10 * ic_p: | |
| out["incremental_roic_5y"] = round(max(-1.0, min(2.0, (nopat_c - nopat_p) / (ic_c - ic_p))), 3) | |
| elif ic_c and ic_p and ic_c <= ic_p and nopat_c > nopat_p: | |
| out["capital_light"] = True # profits up on less capital | |
| # buybacks vs dilution (basic shares, 1y and 5y) | |
| if sh and len(a) >= 2 and _f(a[1].get("sharesbas")): | |
| out["buyback_yield_1y"] = round(-(sh / _f(a[1]["sharesbas"]) - 1), 4) | |
| if sh and len(a) >= 6 and _f(a[5].get("sharesbas")): | |
| out["share_change_5y"] = round(sh / _f(a[5]["sharesbas"]) - 1, 4) | |
| sbc = _f(c.get("sbcomp")) | |
| if sbc is not None and rev: | |
| out["sbc_pct_rev"] = round(sbc / rev, 4) | |
| if sbc is not None and fcf and fcf > 0: | |
| out["sbc_pct_fcf"] = round(sbc / fcf, 3) | |
| # dividends: FCF payout and growth streak | |
| dps = _f(c.get("dps")) | |
| if dps and sh and fcf and fcf > 0: | |
| out["fcf_payout"] = round(dps * sh / fcf, 3) | |
| streak = 0 | |
| for i in range(len(a) - 1): | |
| d0, d1 = _f(a[i].get("dps")), _f(a[i + 1].get("dps")) | |
| if d0 and d1 and d0 > d1: | |
| streak += 1 | |
| else: | |
| break | |
| out["dividend_streak_years"] = streak if dps else 0 | |
| # growth durability and margin trend | |
| revs = [_f(r.get("revenue")) for r in a[:4]] | |
| if len(revs) == 4 and revs[0] and revs[3] and revs[3] > 0: | |
| out["rev_cagr_3y"] = round((revs[0] / revs[3]) ** (1 / 3) - 1, 4) | |
| if len(a) >= 2 and rev: | |
| m0, m1 = _f(c.get("netmargin")), _f(a[1].get("netmargin")) | |
| if m0 is not None and m1 is not None: | |
| out["margin_trend"] = round(m0 - m1, 4) | |
| # Rule of 40 (software / internet / semis only) | |
| ind = (industry or "").lower() | |
| if any(h in ind for h in SOFTWARE_HINT) and rev and fcf is not None and out.get("rev_cagr_3y") is not None: | |
| r1 = (rev / _f(a[1]["revenue"]) - 1) if len(a) > 1 and _f(a[1].get("revenue")) else out["rev_cagr_3y"] | |
| out["rule_of_40"] = round((r1 + fcf / rev) * 100, 1) | |
| # Graham number and Lynch PEG | |
| eps, bvps = _f(c.get("epsdil")) or _f(c.get("eps")), _f(c.get("bvps")) | |
| if eps and bvps and eps > 0 and bvps > 0: | |
| out["graham_number"] = round(math.sqrt(22.5 * eps * bvps), 2) | |
| eps3 = [_f(r.get("epsdil")) or _f(r.get("eps")) for r in a[:4]] | |
| if len(eps3) == 4 and eps3[0] and eps3[3] and eps3[0] > 0 and eps3[3] > 0: | |
| out["eps_cagr_3y"] = round((eps3[0] / eps3[3]) ** (1 / 3) - 1, 4) | |
| pe = _f(c.get("pe")) | |
| g = out.get("eps_cagr_3y") | |
| if pe and pe > 0 and g and g > 0: | |
| out["peg_3y"] = round(pe / (g * 100), 2) # Lynch: P/E Γ· EPS growth | |
| out["lynch_category"] = lynch_category(a, sector, mc, dps) | |
| return out | |
| def lynch_category(a: list[dict], sector: str, mcap: float | None, dps: float | None) -> str: | |
| """Lynch's six boxes β decides which metrics matter for the name.""" | |
| if not a: | |
| return "unclassified" | |
| c = a[0] | |
| revs = [_f(r.get("revenue")) for r in a[:4]] | |
| g = ((revs[0] / revs[3]) ** (1 / 3) - 1) if len(revs) == 4 and revs[0] and revs[3] else None | |
| eps3 = [_f(r.get("epsdil")) or _f(r.get("eps")) for r in a[:4]] | |
| if len(eps3) == 4 and eps3[0] and eps3[3] and eps3[0] > 0 and eps3[3] > 0: | |
| ge = (eps3[0] / eps3[3]) ** (1 / 3) - 1 | |
| g = max(g, ge) if g is not None else ge | |
| if sector == "Real Estate": | |
| return "slow grower" if dps else "asset play" | |
| ni_now = _f(c.get("netinc")) | |
| ni_prev = [_f(r.get("netinc")) for r in a[1:3]] # a loss within the last two years | |
| if ni_now is not None and ni_now > 0 and any(x is not None and x < 0 for x in ni_prev): | |
| return "turnaround" | |
| if sector in CYCLICAL and sector != "Financial Services": | |
| return "cyclical" | |
| if g is not None and g >= 0.20: | |
| return "fast grower" | |
| if g is not None and g >= 0.08: | |
| return "stalwart" | |
| if dps: | |
| return "slow grower" | |
| return "stalwart" if (mcap or 0) > 5e10 else "unclassified" | |
| # ---------------- valuation vs own history ---------------- | |
| def valuation_history(t: str) -> dict: | |
| rows = _ndl("SHARADAR/DAILY", _daily_params(t)) | |
| if len(rows) < 250: | |
| return {} | |
| rows.sort(key=lambda r: str(r.get("date"))) | |
| out = {"years": round(len(rows) / 252, 1), "as_of": str(rows[-1].get("date"))} | |
| cur = rows[-1] | |
| for k in ("pe", "evebitda", "ps", "pb"): | |
| xs = [v for v in (_f(r.get(k)) for r in rows) if v is not None and v > 0] | |
| v = _f(cur.get(k)) | |
| if v and v > 0 and len(xs) >= 250: | |
| xs.sort() | |
| rank = sum(1 for x in xs if x <= v) / len(xs) | |
| out[k] = {"now": round(v, 1), "pctile": round(rank * 100), "median": round(xs[len(xs) // 2], 1)} | |
| return out | |
| # ---------------- ownership ---------------- | |
| def insider_flow(t: str, months: int = 6) -> dict: | |
| rows = _ndl("SHARADAR/SF2", _sf2_params(t, months), ttl_h=24) | |
| buys = sells = 0.0 | |
| buyers, sellers = set(), set() | |
| for r in rows: | |
| code = str(r.get("transactioncode") or "") | |
| if not str(r.get("securityadcode") or "N").startswith("N"): # derivative rows (RSU/option) carry no cash signal | |
| continue | |
| val = _f(r.get("transactionvalue")) | |
| if val is None: | |
| sh, px = _f(r.get("transactionshares")), _f(r.get("transactionpricepershare")) | |
| val = abs(sh * px) if sh and px else None | |
| if not val: | |
| continue | |
| if code == "P": # open-market purchase | |
| buys += val | |
| buyers.add(r.get("ownername")) | |
| elif code == "S": # open-market sale | |
| sells += val | |
| sellers.add(r.get("ownername")) | |
| return {"months": months, "buy_usd": round(buys), "sell_usd": round(sells), "net_usd": round(buys - sells), | |
| "n_buyers": len(buyers), "n_sellers": len(sellers)} | |
| def institution_flow(t: str) -> dict: | |
| rows = _ndl("SHARADAR/SF3A", _sf3a_params(t), ttl_h=24) | |
| rows.sort(key=lambda r: str(r.get("date")), reverse=True) | |
| if len(rows) < 2: | |
| return {} | |
| c, p = rows[0], rows[1] | |
| if str(c.get("date")) < (date.today() - timedelta(days=200)).isoformat(): | |
| return {} # stale 13F coverage β say nothing rather than something old | |
| h0, h1 = _f(c.get("shrholders")), _f(p.get("shrholders")) | |
| u0, u1 = _f(c.get("shrunits")), _f(p.get("shrunits")) | |
| out = {"as_of": c.get("date"), "holders": h0} | |
| if h0 is not None and h1 and abs(h0 / h1 - 1) < 0.30: # >30% jumps are coverage changes, not flows | |
| out["holders_change"] = int(h0 - h1) | |
| out["holders_change_pct"] = round((h0 / h1 - 1) * 100, 1) | |
| if u0 is not None and u1 and abs(u0 / u1 - 1) < 0.30: | |
| out["shares_change_pct"] = round((u0 / u1 - 1) * 100, 1) | |
| return out | |
| # ---------------- earnings momentum (Alpha Vantage) ---------------- | |
| def earnings_momentum(t: str) -> dict: | |
| out: dict = {} | |
| key = f"earn_{t}" | |
| c = _cache_get(key) | |
| if c is not None: | |
| return c | |
| surp: list[float] = [] | |
| try: # surprise history: yfinance is fast and free | |
| import yfinance as yf | |
| eh = yf.Ticker(t).earnings_history | |
| if eh is not None and len(eh): | |
| col = "surprisePercent" if "surprisePercent" in eh.columns else None | |
| if col: | |
| vals = [float(v) for v in eh[col].dropna().tolist()][-8:] | |
| surp = [v * 100 if abs(v) < 1.5 else v for v in reversed(vals)] # fraction β percent | |
| except Exception: | |
| surp = [] | |
| if not surp: # Alpha Vantage as the fallback, one call | |
| e = _av_call({"function": "EARNINGS", "symbol": t}) or {} | |
| q = (e.get("quarterlyEarnings") or [])[:8] if isinstance(e, dict) else [] | |
| surp = [v for v in (_f(x.get("surprisePercentage")) for x in q) if v is not None] | |
| if surp: | |
| out["beats_8q"] = sum(1 for s in surp if s > 0) | |
| out["n_q"] = len(surp) | |
| out["avg_surprise_pct"] = round(sum(surp) / len(surp), 1) | |
| out["last_surprise_pct"] = round(surp[0], 1) | |
| est = _av_call({"function": "EARNINGS_ESTIMATES", "symbol": t}) or {} | |
| fy = [x for x in (est.get("estimates") or []) if isinstance(est, dict) | |
| and str(x.get("horizon", "")).startswith("fiscal year") and str(x.get("date", "")) >= date.today().isoformat()] | |
| fy.sort(key=lambda x: str(x.get("date"))) | |
| if fy: | |
| x = fy[0] | |
| now, ago = _f(x.get("eps_estimate_average")), _f(x.get("eps_estimate_average_90_days_ago")) | |
| if now and ago: | |
| out["fy_eps_est"] = now | |
| out["eps_revision_90d_pct"] = round((now / ago - 1) * 100, 1) | |
| up, dn = _f(x.get("eps_estimate_revision_up_trailing_30_days")), _f(x.get("eps_estimate_revision_down_trailing_30_days")) | |
| if up is not None or dn is not None: | |
| out["revisions_30d"] = {"up": int(up or 0), "down": int(dn or 0)} | |
| out["fy_end"] = x.get("date") | |
| _cache_put(key, out) | |
| return out | |
| # ---------------- assembly ---------------- | |
| def eligible(ticker: str, quote_type: str | None) -> bool: | |
| return "." not in ticker and str(quote_type or "EQUITY").upper() == "EQUITY" and bool(NDL_KEY) | |
| def enrich_us(d: dict, price: float | None) -> dict: | |
| """The `us` block for one holding: scores, economics, valuation history, momentum, ownership.""" | |
| t = d["ticker"] | |
| if not eligible(t, d.get("quote_type")): | |
| return {} | |
| with cf.ThreadPoolExecutor(max_workers=5) as ex: | |
| fa = ex.submit(sf1_annual, t) | |
| fv = ex.submit(valuation_history, t) | |
| fi = ex.submit(insider_flow, t) | |
| fh = ex.submit(institution_flow, t) | |
| fe = ex.submit(earnings_momentum, t) | |
| fs = ex.submit(analyst_view, t) | |
| a = fa.result() | |
| val, ins, inst, earn = fv.result(), fi.result(), fh.result(), fe.result() | |
| try: | |
| street = fs.result() | |
| except Exception: | |
| street = {} | |
| if not a: | |
| return {} | |
| sector = str(d.get("sector") or "").title() | |
| ind = str(d.get("industry") or "").lower() | |
| financial = sector in ("Financial Services", "Real Estate") or "bank" in ind or "insurance" in ind | |
| # Altman's 1968 model was fitted on manufacturers: banks, REITs, regulated utilities and | |
| # telecoms carry structural leverage it misreads as distress β masked, not mis-scored | |
| no_altman = financial or sector == "Utilities" or "telecom" in ind | |
| bank = sector == "Financial Services" or "bank" in ind or "insurance" in ind | |
| mcap = d.get("mcap") | |
| us = {"fiscal_year": str(a[0].get("calendardate") or a[0].get("datekey"))[:10], "years": len(a), "sector": sector, | |
| "piotroski": None if bank else piotroski(a), "altman_z": None if no_altman else altman_z(a[0], mcap), | |
| "beneish_m": None if financial else beneish_m(a), | |
| "econ": economics(a, price, mcap, sector, str(d.get("industry") or "")), | |
| "valuation_hist": val, "insiders": ins, "institutions": inst, "earnings": earn, | |
| "street": street_view(street, price)} | |
| if d.get("adr"): # per-share figures are on the ordinary-share basis β keep only ratio-based ones | |
| for k in ("owner_earnings_ps", "owner_earnings_yield", "graham_number", "peg_3y"): | |
| us["econ"].pop(k, None) | |
| us["adr"] = True | |
| us["flags"] = forensic_flags(us) | |
| us["sell_triggers"] = sell_triggers(d, us) | |
| return us | |
| def street_view(av: dict, price: float | None) -> dict: | |
| """Consensus target as an implied return, with the range as a disagreement gauge.""" | |
| if not av or not price: | |
| return {} | |
| out: dict = {} | |
| tgt = av.get("target") or av.get("target_mean") | |
| if isinstance(tgt, (int, float)) and tgt > 0: | |
| out["target"] = round(float(tgt), 2) | |
| out["implied_return"] = round(float(tgt) / price - 1, 4) | |
| lo, hi = av.get("target_low"), av.get("target_high") | |
| if isinstance(lo, (int, float)) and isinstance(hi, (int, float)) and lo > 0: | |
| out["low"], out["high"] = round(lo, 2), round(hi, 2) | |
| out["spread"] = round((hi - lo) / price, 3) # wide = the street disagrees | |
| if av.get("n_analysts"): | |
| out["n_analysts"] = av["n_analysts"] | |
| r = av.get("ratings") or {} | |
| out["buy_share"] = round((r.get("strong_buy", 0) + r.get("buy", 0)) / av["n_analysts"], 2) | |
| return out | |
| def forensic_flags(us: dict) -> list[str]: | |
| fl = [] | |
| p = us.get("piotroski") or {} | |
| if p and p.get("score", 9) <= 3: | |
| fl.append(f"weak fundamentals momentum (Piotroski {p['score']}/9)") | |
| z = us.get("altman_z") | |
| if z is not None and z < 1.8: | |
| fl.append(f"distress zone (Altman Z {z})") | |
| m = us.get("beneish_m") | |
| if m is not None and m > -1.78: | |
| fl.append(f"earnings-quality warning (Beneish M {m} > β1.78)") | |
| e = us.get("econ") or {} | |
| capital_intensive = str(us.get("sector") or "") in ("Utilities", "Real Estate") # rate-base capex / REIT payout rules | |
| if (e.get("accruals") or 0) > 0.10: | |
| fl.append(f"high accruals ({e['accruals']:.2f} of assets) β earnings outrunning cash") | |
| if e.get("cash_conversion") is not None and 0 < e["cash_conversion"] < 0.6 and not capital_intensive: | |
| fl.append(f"only {e['cash_conversion']:.0%} of profit turns into free cash") | |
| if (e.get("sbc_pct_fcf") or 0) > 0.5: | |
| fl.append(f"stock comp eats {e['sbc_pct_fcf']:.0%} of free cash flow") | |
| if (e.get("share_change_5y") or 0) > 0.15: | |
| fl.append(f"share count up {e['share_change_5y']:.0%} in 5y β dilution") | |
| if e.get("fcf_payout") is not None and e["fcf_payout"] > 1.0 and not capital_intensive: | |
| fl.append(f"dividend exceeds free cash flow (FCF payout {e['fcf_payout']:.0%})") | |
| ins = us.get("insiders") or {} | |
| if ins.get("sell_usd", 0) > 5 * max(ins.get("buy_usd", 0), 1) and ins.get("sell_usd", 0) > 2e7: | |
| fl.append(f"insiders net sellers (${ins['sell_usd'] / 1e6:.0f}M sold vs ${ins.get('buy_usd', 0) / 1e6:.0f}M bought, 6m)") | |
| er = us.get("earnings") or {} | |
| if (er.get("eps_revision_90d_pct") or 0) < -5: | |
| fl.append(f"estimates cut {er['eps_revision_90d_pct']:.0f}% in 90 days") | |
| return fl | |
| def sell_triggers(d: dict, us: dict) -> list[str]: | |
| """Fisher/Lynch sell discipline: the observable facts that would break the thesis.""" | |
| e = us.get("econ") or {} | |
| cat = e.get("lynch_category", "") | |
| tr = [] | |
| def _pct(x): | |
| return f"{x * 100:.0f}%" if isinstance(x, (int, float)) else None | |
| g, peg, payout = _pct(d.get("rev_growth")), d.get("peg"), e.get("fcf_payout") or d.get("payout_ratio") | |
| if cat == "fast grower": | |
| tr.append(f"revenue growth falls below 15% for two consecutive quarters (now {g})" if g | |
| else "revenue growth falls below 15% for two consecutive quarters") | |
| tr.append("gross margin contracts more than 300bp year on year") | |
| elif cat == "stalwart": | |
| tr.append(f"two straight years without earnings growth, or PEG above 2.5 (now {peg:.1f})" | |
| if isinstance(peg, (int, float)) else "two straight years without earnings growth, or PEG above 2.5") | |
| elif cat == "cyclical": | |
| tr.append("peak margins with inventory building faster than sales β sell strength, not weakness" | |
| + (f" (revenue growth now {g})" if g else "")) | |
| elif cat == "slow grower": | |
| tr.append("dividend growth stops or FCF payout exceeds 90%" | |
| + (f" (now {payout * 100:.0f}%)" if isinstance(payout, (int, float)) else "")) | |
| elif cat == "turnaround": | |
| tr.append("free cash flow turns negative again or debt is refinanced at a materially higher cost") | |
| if e.get("roic") is not None: | |
| tr.append(f"ROIC falls below 10% (now {e['roic'] * 100:.0f}%)") | |
| tr.append("Piotroski F-score β€ 3 or Beneish M above β1.78 at the next annual report") | |
| ins = us.get("insiders") or {} | |
| if ins.get("buy_usd", 0) > 0: | |
| tr.append("insiders turn from net buyers to net sellers") | |
| tr.append("price closes below the 200-day average for 20 sessions with estimates being cut") | |
| return tr[:5] | |
| def us_lines(us: dict) -> list[str]: | |
| """Persona brief lines β numbers with the yardstick, never adjectives alone.""" | |
| if not us: | |
| return [] | |
| L = [] | |
| e = us.get("econ") or {} | |
| p = us.get("piotroski") or {} | |
| q = [] | |
| if p: | |
| q.append(f"Piotroski {p['score']}/9") | |
| if us.get("altman_z") is not None: | |
| q.append(f"Altman Z {us['altman_z']} ({'safe' if us['altman_z'] > 2.99 else 'grey' if us['altman_z'] >= 1.8 else 'distress'})") | |
| if us.get("beneish_m") is not None: | |
| q.append(f"Beneish M {us['beneish_m']} ({'clean' if us['beneish_m'] < -1.78 else 'WARNING'})") | |
| if e.get("accruals") is not None: | |
| q.append(f"accruals {e['accruals']:+.2f} of assets") | |
| if e.get("cash_conversion") is not None: | |
| q.append(f"FCF/NI {e['cash_conversion']:.2f}") | |
| if q: | |
| L.append(f"Forensics (FY {us.get('fiscal_year')}): " + ", ".join(q)) | |
| ec = [] | |
| if e.get("roic") is not None: | |
| ec.append(f"ROIC {e['roic'] * 100:.0f}%") | |
| if e.get("incremental_roic_5y") is not None: | |
| ec.append(f"incremental ROIC 5y {e['incremental_roic_5y'] * 100:.0f}%") | |
| elif e.get("capital_light"): | |
| ec.append("profits grew on a SMALLER capital base (capital-light)") | |
| if e.get("eps_cagr_3y") is not None: | |
| ec.append(f"EPS CAGR 3y {e['eps_cagr_3y'] * 100:+.0f}%") | |
| if e.get("owner_earnings_yield") is not None: | |
| ec.append(f"owner-earnings yield {e['owner_earnings_yield'] * 100:.1f}%") | |
| if e.get("fcf_yield") is not None: | |
| ec.append(f"FCF yield {e['fcf_yield'] * 100:.1f}%") | |
| if e.get("greenblatt_ey") is not None: | |
| ec.append(f"EBIT/EV {e['greenblatt_ey'] * 100:.1f}%") | |
| if e.get("graham_number") is not None: | |
| ec.append(f"Graham number {e['graham_number']}") | |
| if e.get("peg_3y") is not None: | |
| ec.append(f"PEG(3y) {e['peg_3y']}") | |
| if e.get("rev_cagr_3y") is not None: | |
| ec.append(f"revenue CAGR 3y {e['rev_cagr_3y'] * 100:+.0f}%") | |
| if e.get("rule_of_40") is not None: | |
| ec.append(f"Rule of 40 = {e['rule_of_40']}") | |
| if ec: | |
| L.append(f"Economics (Lynch: {e.get('lynch_category', '?')}): " + ", ".join(ec)) | |
| ca = [] | |
| if e.get("buyback_yield_1y") is not None: | |
| ca.append(f"buyback yield 1y {e['buyback_yield_1y'] * 100:+.1f}%") | |
| if e.get("share_change_5y") is not None: | |
| ca.append(f"shares 5y {e['share_change_5y'] * 100:+.0f}%") | |
| if e.get("sbc_pct_rev") is not None: | |
| ca.append(f"SBC {e['sbc_pct_rev'] * 100:.1f}% of revenue") | |
| if e.get("fcf_payout") is not None: | |
| ca.append(f"FCF payout {e['fcf_payout'] * 100:.0f}%") | |
| if e.get("dividend_streak_years"): | |
| ca.append(f"dividend raised {e['dividend_streak_years']} straight years") | |
| if e.get("margin_trend") is not None: | |
| ca.append(f"net margin {e['margin_trend'] * 100:+.1f}pp y/y") | |
| if ca: | |
| L.append("Capital allocation: " + ", ".join(ca)) | |
| v = us.get("valuation_hist") or {} | |
| vv = [f"{k.upper()} {x['now']} = {x['pctile']}th pctile of own {v.get('years')}y history (median {x['median']})" | |
| for k, x in v.items() if isinstance(x, dict)] | |
| if vv: | |
| L.append("Valuation vs own history: " + "; ".join(vv)) | |
| er = us.get("earnings") or {} | |
| em = [] | |
| if er.get("n_q"): | |
| em.append(f"beat {er['beats_8q']}/{er['n_q']} recent quarters (avg surprise {er['avg_surprise_pct']:+.1f}%)") | |
| if er.get("eps_revision_90d_pct") is not None: | |
| em.append(f"FY EPS estimate {er['eps_revision_90d_pct']:+.1f}% over 90d") | |
| if er.get("revisions_30d"): | |
| em.append(f"revisions 30d: {er['revisions_30d']['up']} up / {er['revisions_30d']['down']} down") | |
| if em: | |
| L.append("Earnings momentum: " + ", ".join(em)) | |
| st = us.get("street") or {} | |
| if st.get("implied_return") is not None: | |
| L.append(f"Street: consensus target {st['target']} ({st['implied_return'] * 100:+.0f}% vs price)" | |
| + (f", range {st['low']}β{st['high']}" if st.get("low") else "") | |
| + (f", {st['n_analysts']} analysts, {st['buy_share'] * 100:.0f}% buy" if st.get("n_analysts") else "") | |
| + (" β wide disagreement" if (st.get("spread") or 0) > 0.6 else "")) | |
| ins, inst = us.get("insiders") or {}, us.get("institutions") or {} | |
| ow = [] | |
| if ins: | |
| ow.append(f"insiders 6m: bought ${ins['buy_usd'] / 1e6:.1f}M ({ins['n_buyers']}) / sold ${ins['sell_usd'] / 1e6:.1f}M ({ins['n_sellers']})") | |
| if inst.get("holders_change") is not None: | |
| ow.append(f"13F holders {inst['holders_change']:+d} q/q ({inst['holders_change_pct']:+.1f}%)" | |
| + (f", shares held {inst['shares_change_pct']:+.1f}%" if inst.get("shares_change_pct") is not None else "")) | |
| if ow: | |
| L.append("Ownership: " + ", ".join(ow)) | |
| if us.get("flags"): | |
| L.append("FORENSIC FLAGS: " + "; ".join(us["flags"])) | |
| return L | |
| def quick_flags(ticker: str, sector: str | None, quote_type: str | None = None) -> list[str]: | |
| """Cheap forensic screen for a US CANDIDATE (one Sharadar call): the flags that should | |
| keep a name off a recommendation list regardless of its factor rank.""" | |
| if not eligible(ticker, quote_type): | |
| return [] | |
| a = sf1_annual(ticker, n=6) | |
| if len(a) < 2: | |
| return [] | |
| financial = str(sector or "").title() in ("Financial Services", "Real Estate", "Utilities") | |
| us = {"sector": str(sector or "").title(), | |
| "piotroski": None if str(sector or "").title() == "Financial Services" else piotroski(a), | |
| "altman_z": None if financial else altman_z(a[0], None), | |
| "beneish_m": None if financial else beneish_m(a), | |
| "econ": economics(a, None, None, str(sector or "").title(), ""), "insiders": {}, "earnings": {}} | |
| return forensic_flags(us) | |