marketmyna 0.2.0__py3-none-any.whl

marketmyna/bot/commands/research.py

@@ -0,0 +1,323 @@
+"""Stock research from chat: the same services the Analyze page shows
+(quote, overview, valuation, financials, estimates, dividends, peers,
+Shariah screen, compare), as short text replies.
+
+Every command takes SYMBOL [market]; "us:AAPL" works too. Without a
+market the symbol is looked up in the listings (see common.guess_market).
+"""
+
+from __future__ import annotations
+
+from ...utils.deadline import call_with_deadline
+from ..models import CommandResult, IncomingMessage
+from .base import Command
+from .common import big, num, parse_symbol, pct
+
+GROUP = "Stock research"
+
+
+class _SymbolCommand(Command):
+    group = GROUP
+
+    def __init__(self, config):
+        self._config = config
+
+    def handle(self, message: IncomingMessage, args: str) -> CommandResult:
+        symbol, market, rest = parse_symbol(args, self._config)
+        if not symbol:
+            return CommandResult(text=f"Usage: {self.usage}\nExample: {self.example}", success=False)
+        try:
+            return CommandResult(text=self.run(symbol, market, rest))
+        except TimeoutError:
+            return CommandResult(text=f"{symbol}: the data source took too long. Try again.", success=False)
+        except Exception as exc:  # noqa: BLE001 - one bad source must not crash the chat
+            return CommandResult(text=f"{symbol} ({market}): {exc}", success=False)
+
+    def run(self, symbol: str, market: str, rest: list[str]) -> str:
+        raise NotImplementedError
+
+
+class QuoteCommand(_SymbolCommand):
+    name = "quote"
+    aliases = ["q", "price"]
+    usage = "/quote SYMBOL [market]"
+    description = "Live price, day change, day range, volume and market cap."
+    example = "/quote RELIANCE india"
+
+    def run(self, symbol, market, rest):
+        from ...core.constants import Markets
+        from ...data.china import ChinaAFetcher, HongKongFetcher
+        from ...data.crypto import CryptoDataFetcher
+        from ...data.india import IndiaDataFetcher
+        from ...data.stocks import StockDataFetcher
+
+        fetcher = {"india": IndiaDataFetcher, "crypto": CryptoDataFetcher, "china_a": ChinaAFetcher,
+                   "hong_kong": HongKongFetcher}.get(Markets(market).value, StockDataFetcher)()
+        q = call_with_deadline(fetcher.get_quote, 20, symbol) or {}
+        # Exchange quotes can come back thin (e.g. NSE off-hours); fill gaps from the listings row.
+        try:
+            from ...data.listings import get_store
+
+            found = get_store().lookup([(market, kind, symbol) for kind in ("stock", "etf")])
+            row = next(iter(found.values()), {})
+        except Exception:
+            row = {}
+        for key, alt in (("price", "price"), ("open", "open"), ("day_high", "high"), ("day_low", "low"),
+                         ("volume", "volume"), ("market_cap", "market_cap"), ("change_percent", "change_percent")):
+            if not q.get(key) and row.get(alt):
+                q[key] = row[alt]
+        if q.get("price") is None:
+            return f"No quote for {symbol} ({market})."
+        def pair(*items):
+            return " · ".join(f"{label} {fmt(q[key])}" for label, key, fmt in items if q.get(key))
+
+        lines = [f"{symbol} ({market})  {num(q['price'])}  {num(q.get('change'))} ({pct(q.get('change_percent'), 2)})",
+                 pair(("Open", "open", num), ("Prev close", "previous_close", num)),
+                 f"Day range {num(q['day_low'])} - {num(q['day_high'])}" if q.get("day_low") and q.get("day_high") else "",
+                 pair(("Volume", "volume", big), ("Market cap", "market_cap", big))]
+        return "\n".join(line for line in lines if line)
+
+
+class OverviewCommand(_SymbolCommand):
+    name = "overview"
+    aliases = ["ov", "tech"]
+    usage = "/overview SYMBOL [market]"
+    description = "Technicals, trend, returns, risk, fundamentals, analyst consensus and upcoming events."
+    example = "/overview AAPL us"
+
+    def run(self, symbol, market, rest):
+        from ...services.overview import build_overview
+
+        d = call_with_deadline(build_overview, 60, symbol, market)
+        t, r, f, a, e = (d.get(k) or {} for k in ("technical", "risk", "fundamentals", "analysts", "events"))
+        lines = [f"{symbol} ({market}) overview"]
+        if t:
+            counts = t.get("counts")  # absent on a public deploy (no per-stock verdicts)
+            lines.append(f"Trend: {t.get('trend', 'n/a')}" + (
+                f" · indicators {counts.get('buy', 0)} up / {counts.get('sell', 0)} down / "
+                f"{counts.get('neutral', 0)} neutral" if counts else ""))
+            ret = t.get("returns") or {}
+            lines.append("Returns: " + " · ".join(f"{k} {pct(v)}" for k, v in list(ret.items())[:6]))
+            lines.append(f"52w range {num(t.get('low_52w'))} - {num(t.get('high_52w'))} "
+                         f"({pct(t.get('from_high_pct'))} from high)")
+            rsi = next((i for i in t.get("indicators") or [] if i.get("key") == "rsi"), None)
+            if rsi:
+                lines.append(f"RSI(14) {num(rsi.get('value'), 1)}")
+        if r:
+            lines.append(f"Risk: {r.get('level', 'n/a')} · volatility {pct(r.get('volatility_pct'), 1, False)} · "
+                         f"max drawdown {pct(r.get('max_drawdown_pct'))} · beta {num(r.get('beta'))}")
+        if f:
+            lines.append(f"Fundamentals: score {f.get('score', 'n/a')}/100 · health {f.get('health_rating', 'n/a')}")
+        if a.get("count"):
+            # Third-party consensus as a direction (build_overview), without the price targets.
+            lines.append(f"Broker consensus ({a['count']} analysts): {a.get('recommendation') or 'n/a'}")
+        ev = [f"earnings {e['earnings_date']}" if e.get("earnings_date") else "",
+              f"ex-dividend {e['ex_dividend_date']}" if e.get("ex_dividend_date") else ""]
+        if any(ev):
+            lines.append("Events: " + " · ".join(x for x in ev if x))
+        return "\n".join(lines)
+
+
+class ValuationCommand(_SymbolCommand):
+    name = "valuation"
+    aliases = ["val"]
+    usage = "/valuation SYMBOL [market]"
+    description = "Valuation meter: P/E, P/B and other multiples against the sector median, plus the growth-at-a-price check."
+    example = "/valuation INFY india"
+
+    def run(self, symbol, market, rest):
+        from ...services.valuation import meter
+
+        d = call_with_deadline(meter, 90, symbol, market)
+        if d.get("status") != "ok":
+            return f"{symbol}: {d.get('reason') or 'no valuation data'}"
+        zone = {"below": "below its sector", "above": "above its sector", "in_line": "in line with its sector"}
+        lines = [f"{symbol} ({market}) valuation vs {d.get('sector')} ({d.get('peers')} peers): "
+                 f"priced {zone.get(d.get('zone'), d.get('zone'))}"]
+        for m in d.get("multiples") or []:
+            if m.get("value") is not None:
+                lines.append(f"• {m['label']} {num(m['value'])} vs sector median {num(m.get('sector_median'))}")
+        g = d.get("garp") or {}
+        if g.get("total"):
+            lines.append(f"Growth at a reasonable price: {g['passed']}/{g['total']} checks pass (PEG {num(g.get('peg'))})")
+        return "\n".join(lines)
+
+
+class FinancialsCommand(_SymbolCommand):
+    name = "financials"
+    aliases = ["fin"]
+    usage = "/financials SYMBOL [market] [annual|quarterly]"
+    description = "Income statement, balance sheet and cash flow health with the key findings."
+    example = "/financials TCS india"
+
+    def run(self, symbol, market, rest):
+        from ...services.financials import build_financials
+
+        period = "quarterly" if rest and rest[0].lower().startswith("q") else "annual"
+        d = call_with_deadline(build_financials, 60, symbol, market, period)
+        o = d.get("overall") or {}
+        lines = [f"{d.get('name') or symbol} ({market}) {period}: {o.get('label', 'n/a')} ({o.get('score', 'n/a')}/100)"]
+        for key, title in (("income", "Income statement"), ("balance", "Balance sheet"), ("cashflow", "Cash flow")):
+            part = d.get(key) or {}
+            v = part.get("verdict") or {}
+            if not v:
+                continue
+            lines.append(f"{title}: {v.get('label')} ({v.get('score')}) as of {part.get('as_of')}")
+            for f in (part.get("findings") or [])[:3]:
+                lines.append(f"  {'+' if f.get('tone') == 'good' else '-' if f.get('tone') == 'bad' else '·'} {f['text']}")
+        return "\n".join(lines)
+
+
+class EstimatesCommand(_SymbolCommand):
+    name = "estimates"
+    aliases = ["est"]
+    usage = "/estimates SYMBOL [market]"
+    description = "Analyst EPS and revenue consensus, revisions and recent beats or misses."
+    example = "/estimates MSFT us"
+
+    def run(self, symbol, market, rest):
+        from ...services.analysis_run import yahoo_symbol
+        from ...services.estimates import build
+
+        if market == "crypto":
+            return "No analyst estimates for crypto."
+        d = call_with_deadline(build, 45, yahoo_symbol(symbol, market))
+        if not d.get("available"):
+            return f"No analyst estimates for {symbol}."
+        cur = d.get("currency") or ""
+        lines = [f"{symbol} analyst estimates ({cur})"]
+        for p in d.get("periods") or []:
+            eps, rev, r = p.get("eps") or {}, p.get("revenue") or {}, p.get("revisions") or {}
+            growth = eps.get("growth")
+            lines.append(f"• {p['label']}: EPS {num(eps.get('avg'))}"
+                         + (f" ({pct(growth * 100 if abs(growth) < 5 else growth)} y/y)" if growth is not None else "")
+                         + (f", revenue {big(rev.get('avg'))}" if rev.get("avg") else "")
+                         + (f", 30d revisions {int(r.get('up_30d') or 0)} up / {int(r.get('down_30d') or 0)} down" if r else ""))
+        m, b = d.get("momentum") or {}, d.get("beats") or {}
+        if m.get("label"):
+            lines.append(f"Estimate trend (90d): {m['label']}")
+        if b.get("total"):
+            lines.append(f"Beat estimates in {b['beat']} of the last {b['total']} quarters")
+        return "\n".join(lines)
+
+
+class DividendsCommand(_SymbolCommand):
+    name = "dividends"
+    aliases = ["div"]
+    usage = "/dividends SYMBOL [market]"
+    description = "Dividend yield, payout ratio, growth, years without a cut and the last payment."
+    example = "/dividends ITC india"
+
+    def run(self, symbol, market, rest):
+        from ...services.analysis_run import yahoo_symbol
+        from ...services.dividends import build
+
+        if market == "crypto":
+            return "Crypto doesn't pay dividends."
+        d = call_with_deadline(build, 45, yahoo_symbol(symbol, market))
+        if not d.get("pays"):
+            return f"{symbol} has no dividend history."
+        last = d.get("last") or {}
+        return "\n".join([
+            f"{symbol} dividends ({d.get('currency')}) · {d.get('frequency') or 'irregular'}",
+            f"Trailing yield {pct(d.get('ttm_yield'), 2, False)} ({num(d.get('ttm'))} in 12 months) · "
+            f"forward {pct(d.get('forward_yield'), 2, False)}",
+            f"Payout ratio {pct(d.get('payout_ratio'), 0, False)} · 5y growth {pct(d.get('growth_5y'))} · "
+            f"{d.get('years_without_cut', 'n/a')} year{'' if d.get('years_without_cut') == 1 else 's'} without a cut",
+            f"Last paid {num(last.get('amount'))} on {last.get('date', 'n/a')}"
+            + (f" · next ex-date {d['next_ex_date']}" if d.get("next_ex_date") else ""),
+        ])
+
+
+class PeersCommand(_SymbolCommand):
+    name = "peers"
+    aliases = []
+    usage = "/peers SYMBOL [market]"
+    description = "Closest companies in the same sector by size, with P/E and day change."
+    example = "/peers HDFCBANK india"
+
+    def run(self, symbol, market, rest):
+        from ...services.compare import peers
+
+        d = call_with_deadline(peers, 60, symbol, market, 6)
+        rows = d.get("peers") or []
+        if not rows:
+            return f"No peers found for {symbol}."
+        lines = [f"{symbol} peers · {d.get('basis')}"]
+        for p in rows:
+            lines.append(f"• {p['symbol']} cap {big(p.get('market_cap'))} · P/E {num(p.get('pe'), 1)} · "
+                         f"day {pct(p.get('change_percent'))}")
+        lines.append(f"Compare: /compare {symbol}," + ",".join(p["symbol"] for p in rows[:3]) + f" {market}")
+        return "\n".join(lines)
+
+
+class ShariahCommand(_SymbolCommand):
+    name = "ethical"
+    aliases = ["shariah", "halal"]  # the old names keep working
+    usage = "/ethical SYMBOL [market]"
+    description = "Ethical screen: business activity and the debt, cash and interest-income ratios."
+    example = "/ethical AAPL us"
+
+    def run(self, symbol, market, rest):
+        from ...services.shariah import build_shariah_profile
+
+        d = call_with_deadline(build_shariah_profile, 60, symbol, market)
+        lines = [f"{d.get('name') or symbol}: {d.get('verdict_label') or d.get('verdict') or 'no verdict'}"]
+        b = d.get("business") or {}
+        if b.get("reason"):
+            lines.append(f"Business: {b['reason']}")
+        for c in d.get("checks") or []:
+            v = "n/a" if c.get("value") is None else f"{c['value']:.1f}%"
+            lines.append(f"• {c['label']}: {v} (limit {c.get('limit')}%) {c.get('status', '')}")
+        lines.append("A screening aid, not a fatwa.")
+        return "\n".join(lines)
+
+
+class CompareCommand(Command):
+    name = "compare"
+    aliases = ["vs"]
+    usage = "/compare SYM1,SYM2[,SYM3] [market] [6mo|1y|3y|5y]"
+    description = "2-5 stocks side by side: returns, volatility, drawdown, beta and correlation."
+    example = "/compare TCS,INFY,WIPRO india 1y"
+    group = GROUP
+
+    def __init__(self, config):
+        self._config = config
+
+    def handle(self, message: IncomingMessage, args: str) -> CommandResult:
+        from ...services.compare import compare
+        from .common import guess_market, market_word
+
+        parts = args.split()
+        if not parts:
+            return CommandResult(text=f"Usage: {self.usage}\nExample: {self.example}", success=False)
+        market = next((market_word(p) for p in parts[1:] if market_word(p)), None)
+        period = next((p.lower() for p in parts[1:] if p.lower() in ("6mo", "1y", "3y", "5y")), "1y")
+        items = []
+        for tok in parts[0].split(","):
+            if not tok:
+                continue
+            m, _, s = tok.partition(":") if ":" in tok else ("", "", tok)
+            sym = s.upper()
+            items.append((sym, market_word(m) or market or guess_market(sym, self._config)))
+        if not 2 <= len(items) <= 5:
+            return CommandResult(text="Give 2 to 5 symbols, comma separated.", success=False)
+        try:
+            d = call_with_deadline(compare, 60, items, period)
+        except (ValueError, TimeoutError) as exc:
+            return CommandResult(text=str(exc), success=False)
+        syms = [i["symbol"] for i in d.get("items") or []]
+        lines = [f"Compare {', '.join(syms)} ({period})"]
+        for row in d.get("returns") or []:
+            lines.append(f"{row['window']}: " + " · ".join(f"{s} {pct(row['values'].get(s))}" for s in syms))
+        risk = d.get("risk") or {}
+        for s in syms:
+            r = risk.get(s) or {}
+            lines.append(f"{s}: volatility {pct(r.get('volatility'), 1, False)} · max drawdown {pct(r.get('max_drawdown'))} · "
+                         f"beta {num(r.get('beta'))}")
+        corr = d.get("correlation") or {}
+        cs, mx = corr.get("symbols") or [], corr.get("matrix") or []
+        pairs = [f"{cs[i]}/{cs[j]} {mx[i][j]:.2f}" for i in range(len(cs)) for j in range(i + 1, len(cs)) if mx[i][j] is not None]
+        if pairs:
+            lines.append("Correlation: " + " · ".join(pairs[:6]))
+        return CommandResult(text="\n".join(lines))

marketmyna/bot/commands/status.py

@@ -0,0 +1,48 @@
+"""/status - reports the persisted schedule config plus whether the
+scheduler thread is currently running.
+
+Unlike an HTTP endpoint, a bot command has no request.app.state to pull
+the live RuntimeSchedulerService from - `scheduler_running` is an
+optional callable injected by whoever wires the bot into the app (see
+marketmyna/api/app.py's lifespan), so this command never reaches into global
+state itself.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from ...services.schedule_config import ScheduleConfigStore
+from ..models import CommandResult, IncomingMessage
+from .base import Command
+
+
+class StatusCommand(Command):
+    name = "status"
+    aliases = ["s"]
+    usage = "/status"
+    description = "Scheduled-report settings and whether the scheduler is running."
+    group = "System"
+    example = "/status"
+    help_text = "/status - show the scheduled-analysis config and whether it's running"
+
+    def __init__(self, config, scheduler_running: Optional[Callable[[], bool]] = None):
+        self._config = config
+        self._scheduler_running = scheduler_running
+
+    def handle(self, message: IncomingMessage, args: str) -> CommandResult:
+        cfg = ScheduleConfigStore(config=self._config).load()
+
+        running = self._scheduler_running() if self._scheduler_running else None
+        lines = [f"Scheduler thread: {'running' if running else 'not running' if running is not None else 'unknown'}"]
+        lines.append(f"Scheduled analysis: {'enabled' if cfg.enabled else 'disabled'}")
+        if cfg.symbols:
+            lines.append(f"Symbols: {', '.join(cfg.symbols)} ({cfg.market}, {cfg.mode})")
+        if cfg.interval_minutes:
+            lines.append(f"Every {cfg.interval_minutes} minutes")
+        elif cfg.time_of_day:
+            lines.append(f"Daily at {cfg.time_of_day}")
+        if cfg.last_run_at:
+            lines.append(f"Last run: {cfg.last_run_at.isoformat()} ({cfg.last_run_status})")
+
+        return CommandResult(text="\n".join(lines))

marketmyna/bot/commands/trade.py

@@ -0,0 +1,176 @@
+"""Trade section from chat: /alert, /alerts, /risk, /scan.
+
+Symbols take an optional market prefix like the scheduler's STOCK_LIST
+(us:AAPL, crypto:BTC-USD); without one, the Risk tab's market is used."""
+
+from __future__ import annotations
+
+from ...storage import DatabaseManager, PriceAlertRecord, SavedScanRecord, get_db_url
+from ..models import CommandResult, IncomingMessage
+from .base import Command
+
+MARKETS = {"us", "india", "china_a", "hong_kong", "crypto", "global"}
+KIND_WORDS = {
+    "above": "price_above", ">": "price_above", ">=": "price_above",
+    "below": "price_below", "<": "price_below", "<=": "price_below",
+    "up": "pct_up", "down": "pct_down",
+    "rsi>": "rsi_above", "rsi<": "rsi_below",
+    "volume": "volume_spike", "vol": "volume_spike",
+    "breakout": "high_breakout", "breakdown": "low_breakdown",
+}
+
+
+def _db(config):
+    return DatabaseManager.instance(get_db_url(config=config))
+
+
+def _default_market(config) -> str:
+    from ...trading.risk import load_settings
+
+    return load_settings(config).get("market") or "india"
+
+
+def _symbol(token: str, config) -> tuple[str, str]:
+    if ":" in token:
+        market, sym = token.split(":", 1)
+        if market.lower() in MARKETS:
+            return sym.upper(), market.lower()
+    return token.upper(), _default_market(config)
+
+
+class AlertCommand(Command):
+    name = "alert"
+    aliases = ["al"]
+    usage = "/alert SYMBOL above|below PRICE [note]"
+    description = "Create a price alert (also up|down %, rsi>|rsi< N, volume X, breakout|breakdown DAYS)."
+    group = "Trading"
+    example = "/alert india:RELIANCE below 1210"
+    help_text = (
+        "/alert SYMBOL above|below PRICE [note] - price alert; also up|down PCT, rsi>|rsi< N, "
+        "volume X, breakout|breakdown DAYS. Prefix the market: us:AAPL, crypto:BTC-USD"
+    )
+
+    def __init__(self, config):
+        self._config = config
+
+    def handle(self, message: IncomingMessage, args: str) -> CommandResult:
+        from ...trading.alerts import describe
+
+        parts = args.split()
+        if len(parts) < 3:
+            return CommandResult(text=f"Usage: {self.help_text}", success=False)
+        symbol, market = _symbol(parts[0], self._config)
+        kind = KIND_WORDS.get(parts[1].lower())
+        if kind is None:
+            return CommandResult(text=f"Unknown condition '{parts[1]}'. Use one of: {', '.join(sorted(KIND_WORDS))}", success=False)
+        try:
+            value = float(parts[2].rstrip("%x"))
+        except ValueError:
+            return CommandResult(text=f"'{parts[2]}' is not a number", success=False)
+        note = " ".join(parts[3:])
+        with _db(self._config).get_session() as s:
+            rec = PriceAlertRecord(symbol=symbol, market=market, kind=kind, value=value, note=note, status="active", armed=True)
+            s.add(rec)
+            s.flush()
+            alert_id = rec.id
+        return CommandResult(text=f"🔔 Alert #{alert_id} set: {symbol} ({market}) {describe(kind, value)}")
+
+
+class AlertsCommand(Command):
+    name = "alerts"
+    aliases = []
+    usage = "/alerts [delete|pause|resume ID]"
+    description = "List your active alerts, or delete / pause / resume one."
+    group = "Trading"
+    example = "/alerts"
+    help_text = "/alerts - list active alerts · /alerts delete ID · /alerts pause ID · /alerts resume ID"
+
+    def __init__(self, config):
+        self._config = config
+
+    def handle(self, message: IncomingMessage, args: str) -> CommandResult:
+        from ...trading.alerts import describe
+
+        parts = args.split()
+        if len(parts) == 2 and parts[0] in ("delete", "pause", "resume") and parts[1].lstrip("#").isdigit():
+            alert_id = int(parts[1].lstrip("#"))
+            with _db(self._config).get_session() as s:
+                rec = s.get(PriceAlertRecord, alert_id)
+                if rec is None:
+                    return CommandResult(text=f"No alert #{alert_id}", success=False)
+                if parts[0] == "delete":
+                    s.delete(rec)
+                else:
+                    rec.status = "paused" if parts[0] == "pause" else "active"
+                    rec.armed = True
+            return CommandResult(text=f"Alert #{alert_id} {parts[0]}d")
+        with _db(self._config).get_session() as s:
+            recs = s.query(PriceAlertRecord).filter(PriceAlertRecord.status.in_(["active", "paused"])).order_by(PriceAlertRecord.id).all()
+            if not recs:
+                return CommandResult(text="No active alerts. Create one with /alert RELIANCE below 1210")
+            lines = [f"#{r.id} {r.symbol} ({r.market}): {describe(r.kind, r.value)}"
+                     + (" [paused]" if r.status == "paused" else "") + (f" · {r.note}" if r.note else "") for r in recs]
+        return CommandResult(text="\n".join(lines))
+
+
+class RiskCommand(Command):
+    name = "risk"
+    aliases = []
+    usage = "/risk"
+    description = "Today's P&L against your daily loss limit, open risk and trade count."
+    group = "Trading"
+    example = "/risk"
+    help_text = "/risk - today's P&L against your daily loss limit, open risk and trade count"
+
+    def __init__(self, config):
+        self._config = config
+
+    def handle(self, message: IncomingMessage, args: str) -> CommandResult:
+        from ...trading.risk import status
+
+        r = status(self._config)
+        icon = {"ok": "✅", "warn": "⚠️", "stop": "🛑"}[r["status"]]
+        lines = [
+            f"{icon} Risk: {r['status'].upper()} ({r['settings']['market']})",
+            f"Net P&L today: {r['day_pnl']:,.2f} (realised {r['realized']:,.2f}, open {r['unrealized']:,.2f})",
+            f"Loss limit: {r['loss_limit']:,.2f}" + (f" · {r['limit_used_pct']}% used" if r["limit_used_pct"] else ""),
+            f"Open risk to stops: {r['open_risk']:,.2f} ({r['open_risk_pct']}% of capital)",
+            f"Trades today: {r['trades_today']} / {r['settings']['max_trades_per_day']}",
+        ]
+        lines += [f"• {x}" for x in r["reasons"]]
+        return CommandResult(text="\n".join(lines))
+
+
+class ScanCommand(Command):
+    name = "scan"
+    aliases = []
+    usage = "/scan [NAME|ID]"
+    description = "List saved scans, or run one now."
+    group = "Trading"
+    example = "/scan"
+    help_text = "/scan - list saved scans · /scan NAME or ID - run one now"
+
+    def __init__(self, config):
+        self._config = config
+
+    def handle(self, message: IncomingMessage, args: str) -> CommandResult:
+        from ...trading.scanner import run_saved_scans
+
+        with _db(self._config).get_session() as s:
+            saved = [(r.id, r.name) for r in s.query(SavedScanRecord).order_by(SavedScanRecord.id)]
+        if not saved:
+            return CommandResult(text="No saved scans. Save one in Trade → Scanner.")
+        key = args.strip().lstrip("#").lower()
+        if not key:
+            return CommandResult(text="\n".join(f"#{i} {n}" for i, n in saved) + "\nRun one with /scan NAME")
+        match = next((i for i, n in saved if str(i) == key or n.lower() == key), None) or next(
+            (i for i, n in saved if key in n.lower()), None)
+        if match is None:
+            return CommandResult(text=f"No saved scan matches '{args.strip()}'", success=False)
+        out = run_saved_scans(self._config, force_id=match)[0]
+        if not out["rows"]:
+            return CommandResult(text=f"🔎 {out['name']}: no matches in {out['scanned']} stocks")
+        lines = [f"🔎 {out['name']}: {len(out['rows'])} matches in {out['scanned']} stocks"]
+        for r in out["rows"][:20]:
+            lines.append(f"• {r['symbol']} {r['price']:,.2f} ({r['change_percent']:+.1f}%): {', '.join(r['reasons'][:2])}")
+        return CommandResult(text="\n".join(lines))

marketmyna/bot/dispatcher.py

@@ -0,0 +1,95 @@
+"""Routes an IncomingMessage to a registered Command.
+
+Parsing is forgiving: "/analyze AAPL" is the normal form, but a bare
+"analyze AAPL" (first word matching a registered command name/alias,
+no leading slash) also routes correctly. Anything else with no
+recognized command word falls through to the "ask" command if one is
+registered (so a plain question like "should I buy AAPL?" gets a
+useful answer instead of an "unknown command" reply) - the same
+graceful-fallback shape as daily_stock_analysis's own dispatcher, kept
+much smaller here (no rate limiting, no admin users, no NL-intent LLM
+routing - none of that is in scope for this phase).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .commands.base import Command
+from .models import CommandResult, IncomingMessage
+
+logger = logging.getLogger(__name__)
+
+
+class CommandDispatcher:
+    def __init__(self, command_prefix: str = "/"):
+        self.command_prefix = command_prefix
+        self._commands: dict[str, Command] = {}
+        self._aliases: dict[str, str] = {}
+
+    def register(self, command: Command) -> None:
+        name = command.name.lower()
+        if name in self._commands:
+            logger.warning("Command '%s' already registered, overwriting", name)
+        self._commands[name] = command
+        for alias in command.aliases:
+            self._aliases[alias.lower()] = name
+
+    def get_command(self, name: str) -> "Command | None":
+        name = name.lower()
+        if name in self._commands:
+            return self._commands[name]
+        if name in self._aliases:
+            return self._commands.get(self._aliases[name])
+        return None
+
+    def list_commands(self) -> list[Command]:
+        return sorted(self._commands.values(), key=lambda c: c.name)
+
+    # Reference order of the groups; anything else goes after, then "System".
+    GROUP_ORDER = ("Stock research", "AI analysis", "Markets", "Portfolio", "Trading")
+
+    def groups(self) -> dict[str, list[Command]]:
+        """Commands by group, in registration order within a group."""
+        out: dict[str, list[Command]] = {}
+        for command in self._commands.values():
+            out.setdefault(command.group, []).append(command)
+        rank = {g: i for i, g in enumerate(self.GROUP_ORDER)}
+        return dict(sorted(out.items(), key=lambda kv: (kv[0] == "System", rank.get(kv[0], len(rank)))))
+
+    def _split(self, text: str) -> tuple[str, str]:
+        stripped = text.strip()
+        if not stripped:
+            return "", ""
+        parts = stripped.split(maxsplit=1)
+        return parts[0], (parts[1] if len(parts) > 1 else "")
+
+    def dispatch(self, message: IncomingMessage) -> CommandResult:
+        text = (message.text or "").strip()
+        if not text:
+            return CommandResult(text="", success=True)
+
+        if text.startswith(self.command_prefix):
+            head, args = self._split(text[len(self.command_prefix) :])
+        else:
+            head, args = self._split(text)
+
+        command = self.get_command(head) if head else None
+
+        if command is None:
+            # No recognized command word - if the message started with the
+            # prefix, that's a genuine unknown-command; otherwise treat the
+            # whole message as a free-form question for "ask", if present.
+            if text.startswith(self.command_prefix) or "ask" not in self._commands:
+                return CommandResult(
+                    text=f"Unknown command. Try {self.command_prefix}help for a list of commands.",
+                    success=False,
+                )
+            command = self._commands["ask"]
+            args = text
+
+        try:
+            return command.handle(message, args)
+        except Exception as exc:  # noqa: BLE001 - a command must never crash the listener
+            logger.exception("Command '%s' failed", command.name)
+            return CommandResult(text=f"Command failed: {exc}", success=False)

marketmyna/bot/formatting.py

@@ -0,0 +1,25 @@
+"""Turns a dashboard dict (marketmyna/agent/dashboard.py's build_dashboard output)
+into a short human-readable chat message - not a raw JSON dump."""
+
+from __future__ import annotations
+
+
+def format_dashboard(dashboard: dict) -> str:
+    outlook = dashboard.get("outlook")
+    lines = [f"{dashboard['symbol']} ({dashboard['market']}) - {f'{outlook} outlook' if outlook else 'AI analysis'}"]
+
+    summary = dashboard.get("analysis_summary")
+    if summary:
+        lines.append(summary)
+
+    target = dashboard.get("target_price")
+    stop = dashboard.get("stop_loss")
+    if target is not None or stop is not None:
+        lines.append(f"Target: {target if target is not None else 'n/a'}  Stop: {stop if stop is not None else 'n/a'}")
+
+    if dashboard.get("technical_signal"):
+        lines.append(f"Technical: {dashboard['technical_signal']}")
+    if dashboard.get("risk_level"):
+        lines.append(f"Risk: {dashboard['risk_level']}")
+
+    return "\n".join(lines)