marketmyna 0.2.0__py3-none-any.whl

marketmyna/services/thesis.py

@@ -0,0 +1,328 @@
+"""Thesis tracker: why you own (or watch) a stock, kept honest against data.
+
+Adapted from the thesis-tracker skill in anthropics/financial-services
+(Apache-2.0). A thesis should be falsifiable, so it carries:
+
+  statement    1-2 sentences ("margins expand as the mix shifts to software")
+  pillars      up to 5 supporting points, each on track / watch / broken
+  risks        up to 5 things that would invalidate it
+  exit_below   the price at which the thesis is broken; exit_note for the rest
+  target       what it is worth if the thesis plays out
+  conviction   high / medium / low
+  log          dated updates: what happened and whether it strengthened or
+               weakened the thesis - disconfirming evidence included
+
+The data check sets the thesis against live numbers: price vs the exit and
+target levels, the next results date, estimate revisions, pillars marked
+broken and whether the quarterly review is overdue. All of it is the user's
+own view measured against arithmetic - nothing here is a recommendation.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from datetime import date, datetime
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+STATUSES = ("on_track", "watch", "broken")
+IMPACTS = ("strengthens", "weakens", "neutral")
+CONVICTIONS = ("high", "medium", "low")
+MAX_ITEMS = 5
+MAX_LOG = 200
+REVIEW_DAYS = 90  # review at least quarterly, even when nothing happens
+REARM = 0.03  # an exit / target alert re-arms once the price is 3% back on the other side
+ALERT_EVERY = 30 * 60  # price checks per user at most this often
+
+_last_run: dict[Optional[int], float] = {}
+
+
+class ThesisError(ValueError):
+    pass
+
+
+def _db(config):
+    from ..storage import DatabaseManager, get_db_url
+
+    return DatabaseManager.instance(get_db_url(config=config))
+
+
+def to_dict(r) -> dict:
+    return {"id": r.id, "symbol": r.symbol, "market": r.market, "statement": r.statement,
+            "pillars": r.pillars or [], "risks": r.risks or [], "exit_below": r.exit_below,
+            "exit_note": r.exit_note or "", "target": r.target, "conviction": r.conviction or "medium",
+            "log": r.log or [], "created_at": r.created_at.date().isoformat() if r.created_at else None,
+            "reviewed_at": r.reviewed_at, "alerted": r.alerted or {}}
+
+
+def _clean(fields: dict) -> dict:
+    out = {}
+    if "statement" in fields:
+        text = (fields["statement"] or "").strip()
+        if not text:
+            raise ThesisError("Write the thesis in a sentence or two")
+        out["statement"] = text[:2000]
+    if "pillars" in fields:
+        pillars = []
+        for p in (fields["pillars"] or [])[:MAX_ITEMS]:
+            text = str((p or {}).get("text", "")).strip()[:300]
+            if text:
+                status = (p or {}).get("status") or "on_track"
+                if status not in STATUSES:
+                    raise ThesisError(f"Unknown pillar status '{status}'")
+                pillars.append({"text": text, "status": status})
+        out["pillars"] = pillars
+    if "risks" in fields:
+        out["risks"] = [str(r).strip()[:300] for r in (fields["risks"] or [])[:MAX_ITEMS] if str(r).strip()]
+    for key in ("exit_below", "target"):
+        if key in fields:
+            v = fields[key]
+            if v is not None and (not isinstance(v, (int, float)) or v <= 0):
+                raise ThesisError(f"{key.replace('_', ' ').capitalize()} must be a price above 0")
+            out[key] = float(v) if v is not None else None
+    if out.get("exit_below") and out.get("target") and out["exit_below"] >= out["target"]:
+        raise ThesisError("The exit price should be below the target")
+    if "exit_note" in fields:
+        out["exit_note"] = (fields["exit_note"] or "").strip()[:500]
+    if "conviction" in fields:
+        if fields["conviction"] not in CONVICTIONS:
+            raise ThesisError("Conviction is high, medium or low")
+        out["conviction"] = fields["conviction"]
+    return out
+
+
+def get(config, symbol: str, market: str) -> Optional[dict]:
+    from ..storage import ThesisRecord
+
+    with _db(config).get_session() as s:
+        r = s.query(ThesisRecord).filter(ThesisRecord.symbol == symbol, ThesisRecord.market == market).first()
+        return to_dict(r) if r else None
+
+
+def list_all(config) -> list[dict]:
+    from ..storage import ThesisRecord
+
+    with _db(config).get_session() as s:
+        return [to_dict(r) for r in s.query(ThesisRecord).order_by(ThesisRecord.symbol)]
+
+
+def save(config, symbol: str, market: str, **fields) -> dict:
+    """Create or update the thesis for one stock."""
+    from ..storage import ThesisRecord
+
+    clean = _clean(fields)
+    with _db(config).get_session() as s:
+        r = s.query(ThesisRecord).filter(ThesisRecord.symbol == symbol, ThesisRecord.market == market).first()
+        if r is None:
+            if "statement" not in clean:
+                raise ThesisError("Write the thesis in a sentence or two")
+            r = ThesisRecord(symbol=symbol, market=market, conviction="medium", created_at=datetime.now(),
+                             reviewed_at=date.today().isoformat(), log=[])
+            s.add(r)
+        changed_levels = {"exit_below", "target"} & set(clean)
+        for k, v in clean.items():
+            setattr(r, k, v)
+        if changed_levels:  # new levels: their alerts may fire again
+            r.alerted = {k: v for k, v in (r.alerted or {}).items() if k not in ("exit", "target")}
+        s.flush()
+        return to_dict(r)
+
+
+def add_log(config, thesis_id: int, note: str, impact: str, conviction: Optional[str] = None,
+            day: Optional[str] = None) -> Optional[dict]:
+    """A dated update; adding one counts as a review."""
+    from ..storage import ThesisRecord
+
+    note = (note or "").strip()[:1000]
+    if not note:
+        raise ThesisError("Write what happened")
+    if impact not in IMPACTS:
+        raise ThesisError("Impact is strengthens, weakens or neutral")
+    if conviction is not None and conviction not in CONVICTIONS:
+        raise ThesisError("Conviction is high, medium or low")
+    with _db(config).get_session() as s:
+        r = s.query(ThesisRecord).filter(ThesisRecord.id == thesis_id).first()
+        if r is None:
+            return None
+        today = day or date.today().isoformat()
+        entry = {"date": today, "note": note, "impact": impact, "conviction": conviction or r.conviction}
+        r.log = ([entry] + list(r.log or []))[:MAX_LOG]  # newest first
+        if conviction:
+            r.conviction = conviction
+        r.reviewed_at = today
+        r.alerted = {k: v for k, v in (r.alerted or {}).items() if k != "review"}
+        s.flush()
+        return to_dict(r)
+
+
+def mark_reviewed(config, thesis_id: int, day: Optional[str] = None) -> Optional[dict]:
+    from ..storage import ThesisRecord
+
+    with _db(config).get_session() as s:
+        r = s.query(ThesisRecord).filter(ThesisRecord.id == thesis_id).first()
+        if r is None:
+            return None
+        r.reviewed_at = day or date.today().isoformat()
+        r.alerted = {k: v for k, v in (r.alerted or {}).items() if k != "review"}
+        s.flush()
+        return to_dict(r)
+
+
+def delete(config, thesis_id: int) -> bool:
+    from ..storage import ThesisRecord
+
+    with _db(config).get_session() as s:
+        return bool(s.query(ThesisRecord).filter(ThesisRecord.id == thesis_id).delete())
+
+
+# ------------------------------------------------------------------ data check
+
+
+def review_due(t: dict, today: date) -> Optional[int]:
+    """Days since the last review when it is overdue, else None."""
+    last = t.get("reviewed_at") or t.get("created_at")
+    if not last:
+        return None
+    days = (today - date.fromisoformat(last)).days
+    return days if days >= REVIEW_DAYS else None
+
+
+def check(t: dict, price: Optional[float], earnings: Optional[dict] = None, today: Optional[date] = None) -> list[dict]:
+    """The thesis against live numbers: [{tone: up | down | warn | info, text}]."""
+    today = today or date.today()
+    out = []
+    if price:
+        if t.get("exit_below"):
+            gap = (price / t["exit_below"] - 1) * 100
+            if price <= t["exit_below"]:
+                out.append({"tone": "down", "key": "exit",
+                            "text": f"Price {price:,.2f} is at or below your exit level {t['exit_below']:,.2f}: "
+                                    "by your own rule the thesis is broken."})
+            else:
+                out.append({"tone": "info", "key": "exit",
+                            "text": f"{gap:.1f}% above your exit level {t['exit_below']:,.2f}."})
+        if t.get("target"):
+            if price >= t["target"]:
+                out.append({"tone": "up", "key": "target",
+                            "text": f"Price {price:,.2f} has reached your target {t['target']:,.2f}: time to "
+                                    "decide whether the thesis still has room to run."})
+            else:
+                out.append({"tone": "info", "key": "target",
+                            "text": f"Your target {t['target']:,.2f} is {(t['target'] / price - 1) * 100:.1f}% above the price."})
+    pillars = t.get("pillars") or []
+    broken = [p for p in pillars if p["status"] == "broken"]
+    watch = [p for p in pillars if p["status"] == "watch"]
+    if broken:
+        out.append({"tone": "down", "key": "pillars",
+                    "text": f"{len(broken)} of {len(pillars)} pillars marked broken: is the thesis still intact?"})
+    elif watch:
+        out.append({"tone": "warn", "key": "pillars", "text": f"{len(watch)} of {len(pillars)} pillars on watch."})
+    weak = [e for e in (t.get("log") or [])[:3] if e.get("impact") == "weakens"]
+    if len(weak) >= 2:
+        out.append({"tone": "warn", "key": "log",
+                    "text": f"{len(weak)} of your last 3 updates weakened the thesis."})
+    due = review_due(t, today)
+    if due is not None:
+        out.append({"tone": "warn", "key": "review",
+                    "text": f"Last reviewed {due} days ago: review at least quarterly, even when nothing happened."})
+    if earnings:
+        nxt, days = earnings.get("next"), earnings.get("days_to_next")
+        if nxt and days is not None and 0 <= days <= 21:
+            out.append({"tone": "info", "key": "earnings",
+                        "text": f"Results on {nxt['date']} ({'today' if days == 0 else f'in {days} days'}): "
+                                "a fresh data point for each pillar."})
+        latest = earnings.get("latest")
+        if latest and latest.get("actual") is not None and latest.get("surprise") is not None:
+            word = "beat" if latest["surprise"] > 0 else "missed"
+            out.append({"tone": "info", "key": "results",
+                        "text": f"Just reported: EPS {word} estimates by {abs(latest['surprise']):.1f}%. "
+                                "Log what it means for the thesis."})
+        momentum = ((earnings.get("consensus") or {}).get("momentum") or {}).get("label")
+        if momentum == "falling":
+            out.append({"tone": "warn", "key": "estimates", "text": "Analysts' estimates are falling (90 days)."})
+        elif momentum == "rising":
+            out.append({"tone": "up", "key": "estimates", "text": "Analysts' estimates are rising (90 days)."})
+    return out
+
+
+def _price(symbol: str, market: str) -> Optional[float]:
+    from ..agent.agents import _resolve_fetcher
+
+    try:
+        return float((_resolve_fetcher(market).get_quote(symbol) or {}).get("price") or 0) or None
+    except Exception as exc:
+        logger.info("Thesis price for %s unavailable: %s", symbol, exc)
+        return None
+
+
+def _earnings(symbol: str, market: str) -> Optional[dict]:
+    from .earnings import build
+
+    try:
+        return build(symbol, market, with_options=False)
+    except Exception as exc:
+        logger.info("Thesis earnings for %s unavailable: %s", symbol, exc)
+        return None
+
+
+def with_check(t: dict, price: Optional[Callable] = None, earnings: Optional[Callable] = None) -> dict:
+    p = (price or _price)(t["symbol"], t["market"])
+    e = (earnings or _earnings)(t["symbol"], t["market"]) if t["market"] != "crypto" else None
+    return {**t, "price": p, "signals": check(t, p, e)}
+
+
+# ------------------------------------------------------------------ alerts
+
+
+def check_alerts(config, dispatcher=None, today: Optional[date] = None, price: Optional[Callable] = None,
+                 force: bool = False) -> list[str]:
+    """Monitor hook: one message per thesis when the price crosses the exit or
+    target level, or the quarterly review falls due. Re-arms after the price
+    moves back 3%; a review reminder repeats monthly until reviewed."""
+    from ..core import tenant
+    from ..storage import ThesisRecord
+
+    uid = tenant.current_user_id()
+    clock = time.time()
+    if not force and clock - _last_run.get(uid, 0) < ALERT_EVERY:
+        return []
+    _last_run[uid] = clock
+    today = today or date.today()
+    price = price or _price
+    lines = []
+    with _db(config).get_session() as s:
+        for r in s.query(ThesisRecord).all():
+            t, alerted, changed = to_dict(r), dict(r.alerted or {}), False
+            p = price(r.symbol, r.market) if (r.exit_below or r.target) else None
+            if p and r.exit_below:
+                if p <= r.exit_below and "exit" not in alerted:
+                    lines.append(f"• {r.symbol}: price {p:,.2f} is at or below your exit level {r.exit_below:,.2f}")
+                    alerted["exit"], changed = today.isoformat(), True
+                elif p > r.exit_below * (1 + REARM) and "exit" in alerted:
+                    alerted.pop("exit")
+                    changed = True
+            if p and r.target:
+                if p >= r.target and "target" not in alerted:
+                    lines.append(f"• {r.symbol}: price {p:,.2f} reached your target {r.target:,.2f}")
+                    alerted["target"], changed = today.isoformat(), True
+                elif p < r.target * (1 - REARM) and "target" in alerted:
+                    alerted.pop("target")
+                    changed = True
+            due = review_due(t, today)
+            last = alerted.get("review")
+            if due is not None and (not last or (today - date.fromisoformat(last)).days >= 30):
+                lines.append(f"• {r.symbol}: thesis last reviewed {due} days ago - time for a quarterly review")
+                alerted["review"], changed = today.isoformat(), True
+            if changed:
+                r.alerted = alerted
+    if lines:
+        try:
+            from ..notifiers.dispatcher import NotificationDispatcher
+
+            dispatcher = dispatcher or NotificationDispatcher(config)
+            dispatcher.send_all("📝 Your theses\n" + "\n".join(lines), title="Thesis check", purpose="alert")
+        except Exception as exc:
+            logger.error("Thesis alert failed: %s", exc)
+    return lines

marketmyna/services/translate.py

@@ -0,0 +1,146 @@
+"""English for the Chinese names China A data comes with (opt-in on the page).
+
+No AI needed:
+- Stock names: the company's own English name from Yahoo ("宁德时代" ->
+  "Contemporary Amperex Technology"), fetched only for the symbols on
+  screen and saved for good in ~/.marketmyna/cache/english_names.json.
+  Beijing-exchange stocks Yahoo lacks fall back to pinyin.
+- Free text (block-trade broker branches, ...): a glossary of brokers and
+  standard terms, the rest romanised with pypinyin ("上海浦东新区" ->
+  "Shanghai Pudong Xinqu").
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Callable, Optional
+
+from marketmyna.core.home import app_home
+
+logger = logging.getLogger(__name__)
+
+CJK = re.compile(r"[㐀-鿿]")
+MAX_LOOKUPS = 80  # per request; the rest come on the next scroll / page
+
+# Longest first when applied. Brokers people will recognise, then the
+# boilerplate every branch name carries.
+GLOSSARY = {
+    "机构专用": "Institutional seat",
+    "沪股通专用": "Northbound (Shanghai Connect)",
+    "深股通专用": "Northbound (Shenzhen Connect)",
+    "中国国际金融": "CICC", "中信证券": "CITIC Securities", "中信建投": "CSC Financial", "华泰证券": "Huatai Securities",
+    "国泰君安": "Guotai Junan", "国泰海通": "Guotai Haitong", "海通证券": "Haitong Securities", "招商证券": "China Merchants Securities",
+    "广发证券": "GF Securities", "银河证券": "China Galaxy Securities", "中国银河": "China Galaxy", "申万宏源": "Shenwan Hongyuan",
+    "东方财富": "East Money", "国信证券": "Guosen Securities", "光大证券": "Everbright Securities", "兴业证券": "Industrial Securities",
+    "长江证券": "Changjiang Securities", "方正证券": "Founder Securities", "东方证券": "Orient Securities", "平安证券": "Ping An Securities",
+    "安信证券": "Essence Securities", "国金证券": "Sinolink Securities", "华西证券": "Huaxi Securities", "浙商证券": "Zheshang Securities",
+    "财通证券": "Caitong Securities", "长城证券": "Great Wall Securities", "中泰证券": "Zhongtai Securities", "东吴证券": "Soochow Securities",
+    "华安证券": "Huaan Securities", "国元证券": "Guoyuan Securities", "西部证券": "Western Securities", "天风证券": "Tianfeng Securities",
+    "开源证券": "Kaiyuan Securities", "华鑫证券": "Huaxin Securities", "中金财富": "CICC Wealth", "瑞银证券": "UBS Securities",
+    "摩根大通证券": "J.P. Morgan Securities", "高盛高华": "Goldman Sachs Gao Hua", "华宝证券": "Huabao Securities",
+    "股份有限公司": "", "有限责任公司": "", "有限公司": "", "分公司": " branch", "证券营业部": " branch", "营业部": " branch",
+    "证券": " Securities", "总部": " HQ", "路": " Rd", "大道": " Ave", "大街": " St", "街": " St",
+    "新区": " New Area", "开发区": " Dev Zone", "自贸区": " FTZ",
+}
+_GLOSS = sorted(GLOSSARY.items(), key=lambda kv: -len(kv[0]))
+_SUFFIX = re.compile(r",?\s*(co\.?,?\s*ltd\.?|company limited|co\.?,?\s*limited|limited|corporation|corp\.?|inc\.?)\s*$", re.I)
+
+_lock = threading.Lock()
+_names: Optional[dict[str, str]] = None
+
+
+def has_cjk(text: Optional[str]) -> bool:
+    return bool(text and CJK.search(text))
+
+
+def pinyin(text: str) -> str:
+    """CJK runs -> capitalised pinyin words; everything else kept."""
+    try:
+        from pypinyin import lazy_pinyin
+    except ImportError:
+        return text
+
+    def run(m: re.Match) -> str:
+        # No word segmentation offline; most Chinese place and street names
+        # are two characters, so pair the syllables: "Ningbo Tiantong Bei".
+        syl = lazy_pinyin(m.group(0))
+        return " " + " ".join("".join(syl[i:i + 2]).capitalize() for i in range(0, len(syl), 2)) + " "
+
+    return re.sub(r"[㐀-鿿]+", run, text)
+
+
+def english_text(text: str) -> str:
+    if not has_cjk(text):
+        return text
+    out = text
+    for zh, en in _GLOSS:
+        out = out.replace(zh, f" {en} " if en and not en.startswith(" ") else en)
+    out = pinyin(out)
+    out = re.sub(r"\s+", " ", out).strip()
+    return re.sub(r"\s+([,)])", r"\1", out)
+
+
+def clean_company(name: str) -> str:
+    return _SUFFIX.sub("", (name or "").strip()).strip(" ,")
+
+
+# ------------------------------------------------------------ stock names
+
+
+def _path() -> Path:
+    path = app_home() / "cache"
+    path.mkdir(parents=True, exist_ok=True)
+    return path / "english_names.json"
+
+
+def _load() -> dict[str, str]:
+    global _names
+    if _names is None:
+        try:
+            _names = json.loads(_path().read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            _names = {}
+    return _names
+
+
+def _save() -> None:
+    try:
+        _path().write_text(json.dumps(_names, ensure_ascii=False, indent=0), encoding="utf-8")
+    except OSError as exc:
+        logger.warning("English names cache not saved: %s", exc)
+
+
+def _yahoo_name(yahoo: str) -> Optional[str]:
+    import yfinance as yf
+
+    try:
+        info = yf.Ticker(yahoo).info or {}
+    except Exception:
+        return None
+    name = info.get("longName") or info.get("shortName")
+    return clean_company(name) if name and not has_cjk(name) else None
+
+
+def english_names(items: list[tuple[str, str]], market: str,
+                  lookup: Callable[[str], Optional[str]] = _yahoo_name) -> dict[str, str]:
+    """[(symbol, chinese name)] -> {symbol: English name}. Cached forever;
+    unknown to Yahoo -> pinyin of the Chinese name (also cached)."""
+    from .analysis_run import yahoo_symbol
+
+    with _lock:
+        names = _load()
+        missing = [(s, n) for s, n in items if f"{market}:{s}" not in names][:MAX_LOOKUPS]
+    if missing:
+        with ThreadPoolExecutor(max_workers=8) as pool:
+            found = list(pool.map(lambda sn: lookup(yahoo_symbol(sn[0], market)), missing))
+        with _lock:
+            for (sym, zh), en in zip(missing, found):
+                names[f"{market}:{sym}"] = en or english_text(zh)
+            _save()
+    with _lock:
+        return {s: names[f"{market}:{s}"] for s, _ in items if f"{market}:{s}" in names}

marketmyna/services/valuation.py

@@ -0,0 +1,173 @@
+"""Valuation meter for one stock: how its price compares with its sector.
+
+At today's price, the stock's P/E, price/book and price/sales are each divided
+by the median of the same sector among the market's largest companies (the
+universe the ready-made screens use). The combined position is the geometric
+mean of those multiples:
+
+    below 0.8x  -> priced below its sector
+    0.8 - 1.2x  -> in line with its sector
+    above 1.2x  -> priced above its sector
+
+A separate growth check reports PEG (P/E / earnings growth %) and the rules of
+the "Growth at a reasonable price" screen, each pass/fail, so a dear stock
+that is growing fast is visible as such. Everything is a comparison with
+numbers shown; the label wording is chosen by the frontend (see
+sebi-compliance-mode.md: no bare "overvalued" on public deploys).
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable, Optional
+
+from ..core.numbers import finite as _num
+from ..core.numbers import median as _median
+from ..data.yahoo_price import info_price
+
+UNIVERSE = 200
+MIN_PEERS = 5  # profitable companies a sector needs before its median means anything
+BELOW, ABOVE = 0.8, 1.2
+CACHE_SECONDS = 6 * 3600
+
+# key -> (Yahoo field, label)
+MULTIPLES = {
+    "pe": ("trailingPE", "P/E"),
+    "pb": ("priceToBook", "Price / book"),
+    "ps": ("priceToSalesTrailing12Months", "Price / sales"),
+}
+
+InfoFetch = Callable[[str], dict]
+
+_cache: dict[str, tuple[float, dict]] = {}
+_lock = threading.Lock()
+
+
+def sector_medians(market: str, info_fetch: Optional[InfoFetch] = None, rows: Optional[list[dict]] = None) -> dict:
+    """sector -> {pe, pb, ps: median or None, n: profitable companies}, from
+    the market's largest stocks. Cached for a few hours per market."""
+    if info_fetch is None and rows is None:
+        with _lock:
+            hit = _cache.get(market)
+        if hit and time.time() - hit[0] < CACHE_SECONDS:
+            return hit[1]
+    from .analysis_run import yahoo_symbol
+    from .compare import _yahoo_info
+
+    fetch = info_fetch or _yahoo_info
+    if rows is None:
+        from ..data.listings import get_store
+
+        rows = get_store().rows(market)
+    stocks = sorted((r for r in rows if r.get("type") == "stock" and r.get("market_cap")),
+                    key=lambda r: -r["market_cap"])[:UNIVERSE]
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        infos = list(pool.map(lambda r: fetch(yahoo_symbol(r["symbol"], market)), stocks))
+
+    groups: dict[str, dict[str, list[float]]] = {}
+    for info in infos:
+        sector = (info or {}).get("sector")
+        pe = _num((info or {}).get("trailingPE"))
+        if not sector or not pe or pe <= 0:
+            continue  # loss-makers would drag a P/E median around
+        g = groups.setdefault(sector, {k: [] for k in MULTIPLES})
+        for key, (field, _) in MULTIPLES.items():
+            v = _num(info.get(field))
+            if v and v > 0:
+                g[key].append(v)
+    out = {s: {"n": len(g["pe"]), **{k: _median(g[k]) for k in MULTIPLES}} for s, g in groups.items()}
+    if info_fetch is None and rows is None:
+        with _lock:
+            _cache[market] = (time.time(), out)
+    return out
+
+
+def zone(position: Optional[float]) -> Optional[str]:
+    if position is None:
+        return None
+    if position < BELOW:
+        return "below"
+    if position > ABOVE:
+        return "above"
+    return "in_line"
+
+
+def _garp(info: dict, pe: Optional[float]) -> dict:
+    """PEG and the "Growth at a reasonable price" screen rules, each checked."""
+    from .screens import PRESETS, _rule_text, metrics
+
+    m = metrics(info)
+    growth = m.get("earnings_growth")
+    peg = pe / growth if pe and pe > 0 and growth and growth > 0 else None
+    rules = []
+    for rule in PRESETS["garp"][3]:
+        field, op, value = rule
+        v = m.get(field)
+        ok = v is not None and ((op == ">" and v > value) or (op == "<" and v < value)
+                                or (op == "between" and value[0] < v < value[1]))
+        # pass: True / False, or None when Yahoo has no figure (not counted).
+        rules.append({"rule": _rule_text(rule), "field": field, "value": v, "pass": None if v is None else bool(ok)})
+    known = [r for r in rules if r["pass"] is not None]
+    return {
+        "peg": peg,
+        "earnings_growth": growth,
+        "revenue_growth": m.get("revenue_growth"),
+        "rules": rules,
+        "passed": sum(1 for r in known if r["pass"]),
+        "total": len(known),
+        "missing": len(rules) - len(known),
+    }
+
+
+def meter(symbol: str, market: str, info_fetch: Optional[InfoFetch] = None,
+          medians: Optional[dict] = None) -> dict:
+    from .analysis_run import yahoo_symbol
+    from .compare import _yahoo_info
+
+    if market == "crypto":
+        return {"status": "unavailable", "reason": "Crypto has no earnings or book value to compare."}
+    info = (info_fetch or _yahoo_info)(yahoo_symbol(symbol, market)) or {}
+    if not info:
+        return {"status": "unavailable", "reason": "No fundamentals available for this symbol right now."}
+    sector = info.get("sector")
+    if medians is None:
+        medians = sector_medians(market)
+    peers = medians.get(sector or "") or {}
+
+    pe = _num(info.get("trailingPE"))
+    multiples, ratios = [], []
+    for key, (field, label) in MULTIPLES.items():
+        v = _num(info.get(field))
+        med = peers.get(key) if peers.get("n", 0) >= MIN_PEERS else None
+        ratio = v / med if v and v > 0 and med else None
+        if ratio:
+            ratios.append(ratio)
+        multiples.append({"key": key, "label": label, "value": v, "sector_median": med, "ratio": ratio})
+
+    position = math.exp(sum(math.log(r) for r in ratios) / len(ratios)) if ratios else None
+    reason = None
+    if position is None:
+        if not sector:
+            reason = "Our market data has no sector for this company, so there is no peer group to compare with."
+        elif peers.get("n", 0) < MIN_PEERS:
+            reason = f"Too few profitable {sector} companies among the market's largest to form a sector median."
+        else:
+            reason = "The company has no positive P/E, book value or sales figure to compare (for example a loss-maker)."
+    return {
+        "status": "ok" if position is not None else "unavailable",
+        "reason": reason,
+        "symbol": symbol,
+        "sector": sector,
+        "peers": peers.get("n", 0),
+        "universe": f"the {UNIVERSE} largest companies in this market",
+        "price": info_price(info),
+        "currency": info.get("currency"),
+        "multiples": multiples,
+        "position": position,
+        "zone": zone(position),
+        "bands": {"below": BELOW, "above": ABOVE},
+        "garp": _garp(info, pe),
+    }