marketmyna 0.2.0__py3-none-any.whl

marketmyna/services/mf_portfolio_ai.py

@@ -0,0 +1,195 @@
+"""AI review of a whole mutual fund portfolio (Portfolio page).
+
+Builds a fact sheet from what the page already computes - the fund table
+(marketmyna/services/mf_lumpsum.portfolio_funds) and the health check
+(marketmyna/services/mf_insights.insights) - plus a look-through of the stocks and
+sectors held across all funds, then asks the model to explain it. Wording
+follows marketmyna/core/compliance.py: the owner gets a view and suggested actions,
+public users an explanation without a recommendation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, wait
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+CACHE_SECONDS = 6 * 3600
+# Reasoning models (gpt-oss, Gemini thinking) spend part of max_tokens before
+# answering; too tight a budget cuts the JSON off mid-way.
+MAX_TOKENS = 4500
+LOOK_THROUGH_SECONDS = 60  # holdings files are cached after the first read; don't hang on a slow one
+MIN_COVERAGE = 50  # % of the portfolio whose holdings must be known to show the look-through
+_cache: dict[tuple, tuple[float, dict]] = {}
+_lock = threading.Lock()
+
+
+
+def _r(x, nd=1):
+    return round(x, nd) if isinstance(x, (int, float)) else None
+
+
+def _short(name: str) -> str:
+    return (name or "").split(" - ")[0]
+
+
+def look_through(weights: dict[str, float]) -> dict:
+    """Stocks and sectors across all funds, each fund's holdings scaled by its
+    share of the portfolio. Funds whose holdings can't be read are skipped and
+    reported in `covered_pct`."""
+    from . import fund_holdings
+
+    pool = ThreadPoolExecutor(max_workers=8)
+    futures = {pool.submit(fund_holdings.for_fund, code): code for code in weights}
+    done, _ = wait(futures, timeout=LOOK_THROUGH_SECONDS)
+    pool.shutdown(wait=False, cancel_futures=True)
+
+    stocks: dict[str, float] = {}
+    sectors: dict[str, float] = {}
+    covered = 0.0
+    for fut in done:
+        try:
+            h = fut.result()
+        except Exception:
+            continue
+        if not isinstance(h, dict) or h.get("status") != "ok":
+            continue
+        w = weights[futures[fut]]
+        covered += w
+        for x in h.get("holdings") or []:
+            if x.get("kind") not in ("equity", "foreign_equity") or not x.get("weight"):
+                continue
+            stocks[x["name"]] = stocks.get(x["name"], 0) + w * x["weight"]
+        for s in h.get("sectors") or []:
+            if s.get("weight"):
+                sectors[s["name"]] = sectors.get(s["name"], 0) + w * s["weight"]
+
+    def top(d, n):
+        return [f"{k} {_r(v)}%" for k, v in sorted(d.items(), key=lambda kv: -kv[1])[:n]]
+
+    return {"covered_pct": _r(covered * 100, 0), "top_stocks_of_portfolio": top(stocks, 10),
+            "top_sectors_of_portfolio": top(sectors, 8)}
+
+
+def facts(funds_view: dict, health: dict) -> dict:
+    funds = [f for f in funds_view.get("funds") or [] if (f.get("value") or 0) > 0]
+    total = sum(f["value"] for f in funds)
+    invested = sum(f.get("invested") or 0 for f in funds)
+    weights = {f["code"]: f["value"] / total for f in funds} if total else {}
+    out: dict = {
+        "funds": len(funds),
+        "invested": _r(invested, 0),
+        "value": _r(total, 0),
+        "gain_pct": _r((total - invested) / invested * 100, 2) if invested else None,
+        "holdings": [
+            {"code": f["code"], "fund": _short(f.get("name")), "category": f.get("category"),
+             "asset_class": f.get("asset_class"), "weight_pct": _r(weights[f["code"]] * 100),
+             "gain_pct": _r(f.get("gain_pct"), 2),
+             "below_high_pct": _r(((f.get("lumpsum") or {}).get("below_high") or 0) * 100)
+             if (f.get("lumpsum") or {}).get("status") == "ok" else None}
+            for f in sorted(funds, key=lambda f: -f["value"])
+        ],
+    }
+    if health.get("funds"):
+        out["health_check"] = {
+            "score": health.get("score"), "grade": health.get("grade"),
+            "asset_classes_pct": {a["name"]: _r(a["weight"] * 100) for a in health.get("asset_classes") or []},
+            "categories": [f"{c['name']} {_r(c['weight'] * 100)}% ({c['count']} funds)" for c in health.get("categories") or []],
+            "funds_that_move_together": [f"{p['a_name']} & {p['b_name']} (correlation {_r(p['correlation'], 2)})"
+                                         for p in (health.get("similar_pairs") or [])[:5]],
+            "issues": list(health.get("issues") or [])[:6],
+        }
+    if weights:
+        lt = look_through(weights)
+        if (lt["covered_pct"] or 0) >= MIN_COVERAGE:
+            out["look_through"] = lt
+        else:  # a few small funds' stocks would misstate the whole portfolio
+            out["look_through"] = {"covered_pct": lt["covered_pct"],
+                                   "note": "Holdings are known for too little of the portfolio; say nothing about its stocks or sectors."}
+    return out
+
+
+def _system() -> str:
+    shape = ('{"summary": "3-4 sentences on the portfolio as a whole", "strengths": ["2-4 short points"], '
+             '"concerns": ["2-4 short points"], "sections": {"mix": "1-2 sentences", "overlap": "1-2 sentences", '
+             '"concentration": "1-2 sentences", "risk": "1-2 sentences"}, '
+             '"funds": [{"code": "scheme code from the data", "note": "one sentence on this fund\'s role in the portfolio"}]')
+    return (
+        "You explain a mutual fund portfolio to its owner for an analytics tool that is not registered with SEBI as "
+        "an investment adviser or research analyst. Using only the figures given, describe how the portfolio is made "
+        "up: asset mix, categories, funds that move together, look-through stocks and sectors, and how concentrated "
+        "it is. Gains since a recent purchase are too short to say anything about a fund. Describe observations "
+        "only. Never recommend buying, selling, switching, adding, merging or rebalancing, and give no view on "
+        "whether the portfolio or any fund is good. Reply with ONLY a JSON object: " + shape + "}"
+    )
+
+
+def _parse(text: str, codes: set[str]) -> Optional[dict]:
+    from ..llm.json_reply import parse_object
+
+    data = parse_object(text)
+    if not data or not data.get("summary"):
+        return None
+
+    def points(key, n=4):
+        return [str(x) for x in (data.get(key) or []) if x][:n]
+
+    sections = data.get("sections") if isinstance(data.get("sections"), dict) else {}
+    notes = [{"code": str(f.get("code")), "note": str(f["note"])} for f in data.get("funds") or []
+             if isinstance(f, dict) and f.get("note") and str(f.get("code")) in codes]
+    out = {
+        "summary": str(data["summary"]),
+        "strengths": points("strengths"),
+        "concerns": points("concerns"),
+        "sections": {k: str(sections[k]) for k in ("mix", "overlap", "concentration", "risk") if sections.get(k)},
+        "funds": notes,
+        "view": None,  # no verdict or actions (marketmyna/core/compliance.py)
+        "actions": [],
+    }
+    return out
+
+
+def review(name: str, funds_view: dict, health: dict, config, use_cache: bool = True) -> Optional[dict]:
+    """The AI review, or None when the reply can't be used. Raises LookupError
+    with no funds; lets GenerationError through for the endpoint."""
+    from ..core import tenant
+    from ..llm.backend_factory import create_generation_backend
+    from ..llm.protocol import GenerationConfig
+
+    funds = [f for f in funds_view.get("funds") or [] if (f.get("value") or 0) > 0]
+    if not funds:
+        raise LookupError("This portfolio has no mutual funds to review.")
+    # Same user, portfolio and holdings -> same review; any trade changes the key.
+    holdings = ",".join(sorted(f"{f['code']}:{round(f.get('units') or 0, 3)}" for f in funds))
+    key = (str(tenant.current()), name, hashlib.sha1(holdings.encode()).hexdigest())
+    if use_cache:
+        with _lock:
+            hit = _cache.get(key)
+        if hit and time.time() - hit[0] < CACHE_SECONDS:
+            return hit[1]
+
+    sheet = facts(funds_view, health)
+    result = create_generation_backend(config).generate(
+        "Mutual fund portfolio (JSON):\n" + json.dumps(sheet, default=str),
+        GenerationConfig(max_tokens=MAX_TOKENS, timeout=150), system_prompt=_system())
+    out = _parse(result.text, {f["code"] for f in funds})
+    if out is None:
+        text = result.text or ""
+        logger.warning("%s: unusable reply from %s (%d chars): %s ... %s", "Fund portfolio AI review", result.model,
+                       len(text), " ".join(text[:150].split()), " ".join(text[-150:].split()))
+        return None
+    names = {f["code"]: _short(f.get("name")) for f in funds}
+    weights = {h["code"]: h["weight_pct"] for h in sheet["holdings"]}
+    for n in out["funds"]:
+        n.update(name=names.get(n["code"]), weight_pct=weights.get(n["code"]))
+    out.update(generated_at=time.strftime("%Y-%m-%d %H:%M"), compliance="analytics",
+               look_through=sheet.get("look_through"))
+    with _lock:
+        _cache[key] = (time.time(), out)
+    return out

marketmyna/services/nse_events.py

@@ -0,0 +1,98 @@
+"""Exchange-confirmed dates for Indian stocks, from NSE's bulk feeds:
+
+- board meetings (results, dividend, fund raising, split, bonus…), the
+  official results date that Yahoo's estimate is replaced with;
+- corporate actions by ex-date (dividends with the amount, splits, bonus,
+  rights, buybacks).
+
+One fetch covers every stock for the next four months, cached and saved on
+disk through econ_calendar's source cache.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timedelta
+from typing import Callable, Optional
+
+MEETINGS_URL = "https://www.nseindia.com/api/corporate-board-meetings?index=equities&from_date={a}&to_date={b}"
+ACTIONS_URL = "https://www.nseindia.com/api/corporates-corporateActions?index=equities&from_date={a}&to_date={b}"
+AHEAD_DAYS = 125
+TTL = 6 * 3600
+
+# words in a meeting's purpose / description -> the topic shown
+TOPICS = [("financial result", "results"), ("dividend", "dividend"), ("bonus", "bonus"), ("split", "stock split"),
+          ("sub-division", "stock split"), ("buy back", "buyback"), ("buyback", "buyback"),
+          ("fund raising", "fund raising"), ("rights", "rights issue"), ("merger", "merger"),
+          ("amalgamation", "merger"), ("demerger", "demerger")]
+
+# corporate action subject -> label
+ACTION_LABELS = [("dividend", "Dividend"), ("bonus", "Bonus issue"), ("split", "Stock split"),
+                 ("sub-division", "Stock split"), ("rights", "Rights issue"), ("buy back", "Buyback"),
+                 ("buyback", "Buyback"), ("demerger", "Demerger"), ("amalgamation", "Merger"), ("agm", "AGM")]
+
+FetchJson = Callable[[str], object]
+
+
+def _day(text) -> Optional[date]:
+    try:
+        return datetime.strptime(str(text).strip(), "%d-%b-%Y").date()
+    except ValueError:
+        return None
+
+
+def topics(text: str) -> list[str]:
+    low = (text or "").lower()
+    out: list[str] = []
+    for word, topic in TOPICS:
+        if word in low and topic not in out and not (topic == "merger" and "demerger" in low):
+            out.append(topic)
+    return out
+
+
+def parse_meetings(rows) -> list[dict]:
+    """[{symbol, date, topics}], one per company and meeting day."""
+    merged: dict[tuple[str, str], list[str]] = {}
+    for r in rows or []:
+        d = _day(r.get("bm_date"))
+        sym = str(r.get("bm_symbol") or "").upper()
+        if not d or not sym:
+            continue
+        found = topics(f"{r.get('bm_purpose') or ''} {r.get('bm_desc') or ''}")
+        have = merged.setdefault((sym, d.isoformat()), [])
+        have += [t for t in found if t not in have]
+    return [{"symbol": s, "date": d, "topics": t} for (s, d), t in merged.items()]
+
+
+def action_label(subject: str) -> str:
+    low = (subject or "").lower()
+    return next((label for word, label in ACTION_LABELS if word in low), "Corporate action")
+
+
+def parse_actions(rows) -> list[dict]:
+    """[{symbol, date (ex-date), label, subject}]."""
+    out = []
+    for r in rows or []:
+        d = _day(r.get("exDate"))
+        sym = str(r.get("symbol") or "").upper()
+        subject = re.sub(r"\s+", " ", str(r.get("subject") or "")).strip()
+        if d and sym and subject:
+            out.append({"symbol": sym, "date": d.isoformat(), "label": action_label(subject), "subject": subject})
+    return out
+
+
+def _fetch_json(url: str) -> object:
+    from .market_calendar import _get_json
+
+    return _get_json(url)
+
+
+def india_events(fetch: FetchJson = _fetch_json, today: Optional[date] = None) -> dict:
+    """{"meetings": [...], "actions": [...]} from a few days back to four months ahead."""
+    from .econ_calendar import _source
+
+    today = today or date.today()
+    a, b = (today - timedelta(days=5)).strftime("%d-%m-%Y"), (today + timedelta(days=AHEAD_DAYS)).strftime("%d-%m-%Y")
+    meetings, _ = _source("nse_board_meetings", lambda: parse_meetings(fetch(MEETINGS_URL.format(a=a, b=b))), ttl=TTL)
+    actions, _ = _source("nse_corporate_actions", lambda: parse_actions(fetch(ACTIONS_URL.format(a=a, b=b))), ttl=TTL)
+    return {"meetings": meetings, "actions": actions}

marketmyna/services/overview.py

@@ -0,0 +1,366 @@
+"""Stock overview for the Analyze page: every computed fact about one
+stock - technicals, trend, returns, risk, fundamentals, analysts, events,
+profile and news - without any AI call.
+
+Each section is built independently and best-effort: a missing source
+(e.g. no fundamentals for crypto) yields {"error": ...} for that section
+only, never a failed page.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable, Optional
+
+from ..core.numbers import finite as _num
+
+logger = logging.getLogger(__name__)
+
+
+def _pct_change(series, bars: int) -> Optional[float]:
+    if len(series) <= bars:
+        return None
+    past = float(series.iloc[-bars - 1])
+    return (float(series.iloc[-1]) / past - 1) * 100 if past else None
+
+
+def _section(fn: Callable[[], dict]) -> dict:
+    try:
+        return fn()
+    except Exception as exc:
+        logger.info("Overview section failed: %s", exc)
+        return {"error": str(exc) or type(exc).__name__}
+
+
+def _technical(history) -> dict:
+    from ..analysis.technical import TechnicalAnalyzer
+
+    if history is None or len(history) < 30:
+        raise ValueError("not enough price history for indicators")
+    close = history["close"].astype(float)
+    last = float(close.iloc[-1])
+    summary = TechnicalAnalyzer(history).get_summary()
+
+    notes = {
+        "rsi": "Momentum 0-100: below 30 oversold, above 70 overbought",
+        "macd": "Trend momentum; reads bullish or bearish as MACD crosses its signal line",
+        "ma": "Price vs 20- and 50-day averages (value shown: 20-day average)",
+        "bollinger": "Position inside the Bollinger band, % (0 = lower band, 100 = upper band)",
+        "stochastic": "Where the close sits in the recent range: below 20 oversold, above 80 overbought",
+    }
+    indicators = [
+        {"key": key, "name": {"rsi": "RSI (14)", "macd": "MACD", "ma": "Moving averages",
+                              "bollinger": "Bollinger bands", "stochastic": "Stochastic %K"}.get(key, key),
+         "value": _num(info["value"]), "signal": info["signal"], "note": notes.get(key, "")}
+        for key, info in summary["indicators"].items()
+    ]
+
+    extra, patterns = _extra_technicals(history)
+    indicators += extra
+    counts = {"buy": sum(i["signal"] in ("buy", "strong_buy") for i in indicators),
+              "sell": sum(i["signal"] in ("sell", "strong_sell") for i in indicators)}
+    counts["neutral"] = len(indicators) - counts["buy"] - counts["sell"]
+    if counts["buy"] > counts["sell"] + counts["neutral"]:
+        overall = "buy"
+    elif counts["sell"] > counts["buy"] + counts["neutral"]:
+        overall = "sell"
+    else:
+        overall = "neutral"
+
+    averages = []
+    for period in (20, 50, 100, 200):
+        if len(close) >= period:
+            value = float(close.tail(period).mean())
+            averages.append({"period": period, "value": value, "above": last > value,
+                             "distance_pct": (last / value - 1) * 100})
+    above = [a for a in averages if a["period"] in (50, 200)]
+    if len(above) == 2 and all(a["above"] for a in above):
+        trend = "uptrend"
+    elif len(above) == 2 and not any(a["above"] for a in above):
+        trend = "downtrend"
+    else:
+        trend = "sideways / mixed"
+
+    returns = {label: _pct_change(close, bars) for label, bars in
+               (("1W", 5), ("1M", 21), ("3M", 63), ("6M", 126), ("1Y", 250))}
+    window = close.tail(252)
+    return {
+        "overall": overall,
+        "counts": counts,
+        "indicators": indicators,
+        "patterns": patterns,
+        "averages": averages,
+        "trend": trend,
+        "returns": returns,
+        "high_52w": float(window.max()),
+        "low_52w": float(window.min()),
+        "from_high_pct": (last / float(window.max()) - 1) * 100,
+        "as_of": str(history.index[-1])[:10],
+    }
+
+
+def _extra_technicals(history) -> tuple[list[dict], list[dict]]:
+    """Oscillators and trend gauges from marketmyna/trading/indicators.py, plus the
+    candlestick patterns and divergences showing on the latest bar."""
+    from ..trading import indicators as ind
+
+    df = history.rename(columns=str.lower).astype(float)
+    out: list[dict] = []
+
+    def add(key, name, value, signal, note):
+        value = _num(value)
+        if value is not None:
+            out.append({"key": key, "name": name, "value": value, "signal": signal, "note": note})
+
+    band = lambda v, lo, hi: "neutral" if v is None else "buy" if v <= lo else "sell" if v >= hi else "neutral"  # noqa: E731
+    c = _num(ind.cci(df).iloc[-1]) if len(df) >= 20 else None
+    add("cci", "CCI (20)", c, band(c, -100, 100), "Distance from the average price: below -100 oversold, above +100 overbought")
+    if "volume" in df and df["volume"].fillna(0).sum() > 0 and len(df) >= 15:
+        m = _num(ind.mfi(df).iloc[-1])
+        add("mfi", "Money flow index", m, band(m, 20, 80), "Volume-weighted RSI: below 20 oversold, above 80 overbought")
+    w = _num(ind.williams_r(df).iloc[-1]) if len(df) >= 14 else None
+    add("williams_r", "Williams %R", w, band(w, -80, -20), "Close vs 14-day range: below -80 oversold, above -20 overbought")
+    if len(df) >= 30:
+        a = ind.adx(df).iloc[-1]
+        strength = _num(a["adx"])
+        sig = "neutral" if strength is None or strength < 25 else "buy" if a["plus_di"] > a["minus_di"] else "sell"
+        add("adx", "ADX (14)", strength, sig, "Trend strength: above 25 is a trending market; direction from +DI vs -DI")
+        ar = _num(ind.aroon(df)["osc"].iloc[-1])
+        add("aroon", "Aroon oscillator", ar, "neutral" if ar is None else "buy" if ar >= 50 else "sell" if ar <= -50 else "neutral",
+            "Recency of 25-day highs vs lows: above +50 uptrend, below -50 downtrend")
+    if len(df) >= 80:
+        ich = ind.ichimoku(df).iloc[-1]
+        last = float(df["close"].iloc[-1])
+        top, bottom = max(ich["span_a"], ich["span_b"]), min(ich["span_a"], ich["span_b"])
+        sig = "buy" if last > top else "sell" if last < bottom else "neutral"
+        add("ichimoku", "Ichimoku cloud", (last / top - 1) * 100 if last > top else (last / bottom - 1) * 100 if last < bottom else 0.0,
+            sig, "Price vs the cloud, % outside it: above = bullish, inside = undecided, below = bearish")
+
+    patterns = [{"key": k, "name": ind.CANDLE_PATTERNS[k][0], "bias": ind.CANDLE_PATTERNS[k][1]}
+                for k in ind.candle_patterns(df)]
+    if len(df) >= 40:
+        for label, osc in (("RSI", ind.rsi(df["close"])), ("MACD", ind.macd(df["close"])["macd"])):
+            kind = ind.divergence(df, osc)
+            if kind:
+                patterns.append({"key": f"{label.lower()}_{kind}_div", "name": f"{label} {kind} divergence", "bias": kind})
+    return out, patterns
+
+
+def _risk(history, info: dict) -> dict:
+    if history is None or len(history) < 30:
+        raise ValueError("not enough price history for risk")
+    close = history["close"].astype(float)
+    returns = close.pct_change().dropna()
+    volatility = float(returns.std() * math.sqrt(252))
+    drawdown = float(((close - close.cummax()) / close.cummax()).min())
+    level = "high" if volatility > 0.5 or drawdown < -0.35 else "medium" if volatility > 0.25 or drawdown < -0.2 else "low"
+    return {
+        "level": level,
+        "volatility_pct": volatility * 100,
+        "max_drawdown_pct": drawdown * 100,
+        "beta": _num(info.get("beta")),
+        "worst_day_pct": float(returns.min() * 100),
+        "best_day_pct": float(returns.max() * 100),
+        "realized": _realized(history),
+    }
+
+
+def _realized(history) -> Optional[dict]:
+    from ..trading.volatility import summary
+
+    try:
+        return summary(history.rename(columns=str.lower))
+    except Exception as exc:
+        logger.info("Realized volatility unavailable: %s", exc)
+        return None
+
+
+def _fundamentals(info: dict) -> dict:
+    from ..analysis.fundamental import FundamentalAnalyzer, yfinance_fundamentals
+
+    if not info or not (info.get("marketCap") or info.get("trailingPE") or info.get("totalRevenue")):
+        raise ValueError("no fundamentals published for this instrument")
+    norm = yfinance_fundamentals(info)
+    summary = FundamentalAnalyzer(norm).get_summary()
+
+    def pct(key):
+        v = norm.get(key)
+        return v * 100 if v is not None else None
+
+    return {
+        "score": summary.get("overall_score"),
+        "valuation_status": (summary.get("valuation") or {}).get("status"),
+        "health_rating": (summary.get("financial_health") or {}).get("rating"),
+        "currency": info.get("financialCurrency") or info.get("currency"),
+        "groups": [
+            {"title": "Valuation", "items": [
+                {"label": "Market cap", "value": _num(info.get("marketCap")), "kind": "money"},
+                {"label": "P/E (trailing)", "value": norm.get("pe_ratio"), "kind": "ratio"},
+                {"label": "P/E (forward)", "value": norm.get("forward_pe"), "kind": "ratio"},
+                {"label": "PEG", "value": norm.get("peg_ratio"), "kind": "ratio"},
+                {"label": "Price / book", "value": norm.get("price_to_book"), "kind": "ratio"},
+                {"label": "Price / sales", "value": norm.get("price_to_sales"), "kind": "ratio"},
+                {"label": "EV / EBITDA", "value": _num(info.get("enterpriseToEbitda")), "kind": "ratio"},
+            ]},
+            {"title": "Profitability", "items": [
+                {"label": "Return on equity", "value": pct("return_on_equity"), "kind": "pct"},
+                {"label": "Return on assets", "value": pct("return_on_assets"), "kind": "pct"},
+                {"label": "Profit margin", "value": pct("profit_margin"), "kind": "pct"},
+                {"label": "Operating margin", "value": _num(info.get("operatingMargins")) and info["operatingMargins"] * 100, "kind": "pct"},
+                {"label": "EPS (trailing)", "value": _num(info.get("trailingEps")), "kind": "ratio"},
+            ]},
+            {"title": "Growth", "items": [
+                {"label": "Revenue growth (YoY)", "value": pct("revenue_growth"), "kind": "pct"},
+                {"label": "Earnings growth (YoY)", "value": pct("earnings_growth"), "kind": "pct"},
+                {"label": "Revenue (TTM)", "value": _num(info.get("totalRevenue")), "kind": "money"},
+            ]},
+            {"title": "Financial health", "items": [
+                {"label": "Debt / equity", "value": norm.get("debt_to_equity"), "kind": "ratio"},
+                {"label": "Current ratio", "value": norm.get("current_ratio"), "kind": "ratio"},
+                {"label": "Total cash", "value": _num(info.get("totalCash")), "kind": "money"},
+                {"label": "Total debt", "value": _num(info.get("totalDebt")), "kind": "money"},
+                {"label": "Free cash flow", "value": _num(info.get("freeCashflow")), "kind": "money"},
+            ]},
+            {"title": "Dividend", "items": [
+                {"label": "Dividend yield", "value": pct("dividend_yield"), "kind": "pct"},
+                {"label": "Payout ratio", "value": pct("payout_ratio"), "kind": "pct"},
+                {"label": "Dividend per share", "value": _num(info.get("dividendRate")), "kind": "ratio"},
+            ]},
+        ],
+    }
+
+
+def _analysts(info: dict) -> dict:
+    if not info.get("recommendationKey") and not info.get("targetMeanPrice"):
+        raise ValueError("no analyst coverage published")
+    return {
+        "recommendation": info.get("recommendationKey"),
+        "mean_score": _num(info.get("recommendationMean")),  # 1 = strong buy ... 5 = sell
+        "count": info.get("numberOfAnalystOpinions"),
+        "target_mean": _num(info.get("targetMeanPrice")),
+        "target_high": _num(info.get("targetHighPrice")),
+        "target_low": _num(info.get("targetLowPrice")),
+    }
+
+
+def _events(yf_symbol: str) -> dict:
+    import yfinance as yf
+
+    from .analysis_run import _to_str_date
+
+    cal = yf.Ticker(yf_symbol).calendar or {}
+    out = {
+        "earnings_date": _to_str_date(cal.get("Earnings Date")),
+        "ex_dividend_date": _to_str_date(cal.get("Ex-Dividend Date")),
+        "dividend_date": _to_str_date(cal.get("Dividend Date")),
+        "eps_estimate": _num(cal.get("Earnings Average")),
+        "revenue_estimate": _num(cal.get("Revenue Average")),
+    }
+    if not any(out.values()):
+        raise ValueError("no upcoming events published")
+    return out
+
+
+def _profile(info: dict, market: str) -> dict:
+    if not info:
+        raise ValueError("no company profile available")
+    return {
+        "name": info.get("longName") or info.get("shortName"),
+        "sector": info.get("sector"),
+        "industry": info.get("industry"),
+        "country": info.get("country"),
+        "employees": info.get("fullTimeEmployees"),
+        "website": info.get("website"),
+        "summary": info.get("longBusinessSummary"),
+        "exchange": info.get("exchange") or info.get("fullExchangeName"),
+        "currency": info.get("currency"),
+    }
+
+
+def build_overview(symbol: str, market: str) -> dict:
+    """Technicals, risk, fundamentals, analysts, events and news for one
+    stock, without per-stock verdicts (public_view)."""
+    return public_view(_build_overview(symbol, market))
+
+
+def public_view(out: dict) -> dict:
+    """What each indicator reads (bullish / bearish / neutral) instead of a
+    buy / sell call, the overall reading and its counts, and the pattern
+    lean; no "overvalued / undervalued" label (docs/future/sebi-compliance-mode.md,
+    step 10). Trend, moving averages and returns stay; the attributed broker
+    consensus is shown as bullish / neutral / bearish, without price targets."""
+    tech = dict(out.get("technical") or {})
+    if "indicators" in tech:
+        tech["indicators"] = [{**i, "signal": reading(i.get("signal"))} for i in tech["indicators"]]
+    if "overall" in tech:
+        tech["overall"] = reading(tech["overall"])
+    fund = dict(out.get("fundamentals") or {})
+    fund.pop("valuation_status", None)
+    # Third-party consensus as a direction, not a call, and without the brokers' price targets.
+    analysts = {k: v for k, v in (out.get("analysts") or {}).items() if k not in ("target_mean", "target_high", "target_low")}
+    if analysts.get("recommendation"):
+        analysts["recommendation"] = reading(analysts["recommendation"]) or analysts["recommendation"]
+    return {**out, "technical": tech, "fundamentals": fund, "analysts": analysts, "compliance": "analytics"}
+
+
+_READINGS = {"strong_buy": "bullish", "buy": "bullish", "bullish": "bullish", "outperform": "bullish",
+             "strong_sell": "bearish", "sell": "bearish", "bearish": "bearish", "underperform": "bearish",
+             "hold": "neutral", "neutral": "neutral"}
+
+
+def reading(signal):
+    """A buy / sell signal as what the indicator reads, not a call."""
+    return _READINGS.get(str(signal).lower()) if signal else None
+
+
+def _build_overview(symbol: str, market: str) -> dict:
+    from ..agent.agents import _resolve_fetcher
+    from ..data.news_search import stock_news
+    from .analysis_run import yahoo_symbol
+
+    yf_symbol = yahoo_symbol(symbol, market)
+
+    def load_history():
+        return _resolve_fetcher(market).get_history(symbol, period="1y")
+
+    def load_info():
+        if market == "crypto":
+            return {}
+        import yfinance as yf
+
+        return yf.Ticker(yf_symbol).info or {}
+
+    # History, company info and news are independent network calls.
+    with ThreadPoolExecutor(max_workers=3) as pool:
+        history_f = pool.submit(load_history)
+        info_f = pool.submit(load_info)
+        news_f = pool.submit(lambda: stock_news(symbol, market, limit=8))
+        try:
+            history = history_f.result()
+        except Exception as exc:
+            logger.info("Overview history for %s failed: %s", symbol, exc)
+            history = None
+        try:
+            info = info_f.result()
+        except Exception as exc:
+            logger.info("Overview info for %s failed: %s", symbol, exc)
+            info = {}
+        try:
+            news = news_f.result()
+        except Exception as exc:
+            news = {"error": str(exc)}
+
+    not_applicable = {"error": "not applicable to crypto"}
+    return {
+        "symbol": symbol,
+        "market": market,
+        "technical": _section(lambda: _technical(history)),
+        "risk": _section(lambda: _risk(history, info)),
+        "fundamentals": not_applicable if market == "crypto" else _section(lambda: _fundamentals(info)),
+        "analysts": not_applicable if market == "crypto" else _section(lambda: _analysts(info)),
+        "events": not_applicable if market == "crypto" else _section(lambda: _events(yf_symbol)),
+        "profile": not_applicable if market == "crypto" else _section(lambda: _profile(info, market)),
+        "news": news if isinstance(news, dict) else {"items": news},
+    }