vitals / src /fundamentals.py
s-ttp's picture
Manager desk: conviction-ranked funding with cash residual, watch tier, min-size exits, tax-lot plan, watchlist with entry conditions, catalysts, post-trade risk, 12m scenarios, rule-of-40 valuation for loss-makers, specific tripwires
6c814fb verified
Raw History Blame Contribute Delete
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)