"""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)