@drico2008/fincli 0.1.3 → 0.2.2

package/fincli/app/providers/market/symbols.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from fincli.app.providers.market.base import SymbolSearchResult
+
 
 FOREX_CURRENCIES = {
     "AUD",
@@ -129,6 +131,45 @@ class ResolvedSymbol:
     asset_class: str
 
 
+@dataclass(frozen=True, slots=True)
+class SymbolAlias:
+    symbol: str
+    name: str
+    asset_class: str
+    exchange: str = ""
+    currency: str = ""
+    aliases: tuple[str, ...] = ()
+    notes: str = ""
+
+
+SYMBOL_CATALOG: tuple[SymbolAlias, ...] = (
+    SymbolAlias("AAPL", "Apple Inc.", "stock", "NASDAQ", "USD", ("APPLE",)),
+    SymbolAlias("MSFT", "Microsoft Corporation", "stock", "NASDAQ", "USD", ("MICROSOFT",)),
+    SymbolAlias("NVDA", "NVIDIA Corporation", "stock", "NASDAQ", "USD", ("NVIDIA",)),
+    SymbolAlias("TSLA", "Tesla Inc.", "stock", "NASDAQ", "USD", ("TESLA",)),
+    SymbolAlias("SPY", "SPDR S&P 500 ETF Trust", "etf", "NYSE Arca", "USD", ("S&P ETF",)),
+    SymbolAlias("QQQ", "Invesco QQQ Trust", "etf", "NASDAQ", "USD", ("NASDAQ ETF",)),
+    SymbolAlias("SPX", "S&P 500 Index", "index", "US", "USD", ("SP500", "S&P500", "^GSPC")),
+    SymbolAlias("NASDAQ", "Nasdaq Composite Index", "index", "US", "USD", ("IXIC", "^IXIC")),
+    SymbolAlias("DOW", "Dow Jones Industrial Average", "index", "US", "USD", ("DJI", "^DJI")),
+    SymbolAlias("DAX", "DAX Performance Index", "index", "Germany", "EUR", ("^GDAXI",)),
+    SymbolAlias("NIKKEI", "Nikkei 225 Index", "index", "Japan", "JPY", ("N225", "^N225")),
+    SymbolAlias("EURUSD", "Euro / US Dollar", "forex", "FX", "USD", ("EUR/USD", "EURUSD=X")),
+    SymbolAlias("GBPUSD", "British Pound / US Dollar", "forex", "FX", "USD", ("GBP/USD", "GBPUSD=X")),
+    SymbolAlias("USDJPY", "US Dollar / Japanese Yen", "forex", "FX", "JPY", ("USD/JPY", "USDJPY=X")),
+    SymbolAlias("XAUUSD", "Gold Spot / US Dollar", "commodity", "Metals", "USD", ("GOLD", "XAU/USD", "GC=F")),
+    SymbolAlias("XAGUSD", "Silver Spot / US Dollar", "commodity", "Metals", "USD", ("SILVER", "XAG/USD", "SI=F")),
+    SymbolAlias("WTI", "WTI Crude Oil Futures", "commodity", "NYMEX", "USD", ("CL=F", "OIL")),
+    SymbolAlias("BRENT", "Brent Crude Oil Futures", "commodity", "ICE", "USD", ("BZ=F",)),
+    SymbolAlias("BTC-USD", "Bitcoin / US Dollar", "crypto", "Crypto", "USD", ("BTCUSD", "BTCUSDT", "BINANCE:BTCUSDT")),
+    SymbolAlias("ETH-USD", "Ethereum / US Dollar", "crypto", "Crypto", "USD", ("ETHUSD", "ETHUSDT", "BINANCE:ETHUSDT")),
+    SymbolAlias("BBRI", "Bank Rakyat Indonesia", "stock", "IDX", "IDR", ("BBRI.JK",)),
+    SymbolAlias("BBCA", "Bank Central Asia", "stock", "IDX", "IDR", ("BBCA.JK",)),
+    SymbolAlias("BMRI", "Bank Mandiri", "stock", "IDX", "IDR", ("BMRI.JK",)),
+    SymbolAlias("TLKM", "Telkom Indonesia", "stock", "IDX", "IDR", ("TLKM.JK",)),
+)
+
+
 def resolve_yfinance_symbol(symbol: str) -> ResolvedSymbol:
     normalized = _normalize(symbol)
     if normalized in YFINANCE_ALIASES:
@@ -153,6 +194,8 @@ def resolve_twelvedata_symbol(symbol: str) -> ResolvedSymbol:
 
 def resolve_finnhub_symbol(symbol: str) -> ResolvedSymbol:
     normalized = _normalize(symbol)
+    if _is_metal_pair(normalized):
+        return ResolvedSymbol(symbol, f"OANDA:{normalized[:3]}_{normalized[3:]}", "commodity")
     if _is_forex_pair(normalized):
         return ResolvedSymbol(symbol, f"OANDA:{normalized[:3]}_{normalized[3:]}", "forex")
     if normalized.startswith("BINANCE:"):
@@ -162,6 +205,68 @@ def resolve_finnhub_symbol(symbol: str) -> ResolvedSymbol:
     return ResolvedSymbol(symbol, symbol.upper(), "stock")
 
 
+def resolve_provider_symbol(provider: str, symbol: str) -> ResolvedSymbol:
+    provider_name = provider.lower().strip()
+    if provider_name == "yfinance":
+        return resolve_yfinance_symbol(symbol)
+    if provider_name == "twelvedata":
+        return resolve_twelvedata_symbol(symbol)
+    if provider_name == "finnhub":
+        return resolve_finnhub_symbol(symbol)
+    if provider_name == "alphavantage":
+        normalized = _normalize(symbol)
+        if _is_metal_pair(normalized):
+            return ResolvedSymbol(symbol, normalized, "commodity")
+        if _is_forex_pair(normalized):
+            return ResolvedSymbol(symbol, normalized, "forex")
+        if normalized in IDX_ALIASES:
+            return ResolvedSymbol(symbol, normalized, "stock")
+        return ResolvedSymbol(symbol, symbol.strip().upper(), _infer_asset_class(normalized))
+    if provider_name == "custom":
+        normalized = symbol.strip().upper()
+        return ResolvedSymbol(symbol, normalized, _infer_asset_class(normalized))
+    raise ValueError(f"Unknown market provider: {provider}")
+
+
+def provider_symbol_matrix(symbol: str, providers: tuple[str, ...] | None = None) -> dict[str, ResolvedSymbol]:
+    names = providers or ("yfinance", "twelvedata", "finnhub", "alphavantage", "custom")
+    return {name: resolve_provider_symbol(name, symbol) for name in names}
+
+
+def search_symbol_catalog(query: str, limit: int = 12) -> list[SymbolSearchResult]:
+    normalized = _normalize(query)
+    if not normalized:
+        return []
+
+    matches: list[tuple[int, SymbolAlias]] = []
+    for item in SYMBOL_CATALOG:
+        haystack = [item.symbol, item.name, item.asset_class, item.exchange, item.currency, *item.aliases]
+        normalized_haystack = [_normalize(part) for part in haystack if part]
+        score = _match_score(normalized, normalized_haystack)
+        if score > 0:
+            matches.append((score, item))
+
+    matches.sort(key=lambda pair: (-pair[0], pair[1].symbol))
+    results = [_symbol_alias_to_result(item) for _, item in matches[:limit]]
+    if results:
+        return results
+
+    guessed = symbol_search_result(query)
+    return [guessed] if guessed else []
+
+
+def symbol_search_result(symbol: str) -> SymbolSearchResult:
+    matrix = provider_symbol_matrix(symbol)
+    first = next(iter(matrix.values()))
+    return SymbolSearchResult(
+        symbol=symbol.upper(),
+        name=f"{symbol.upper()} (inferred)",
+        asset_class=first.asset_class,
+        provider_symbols={provider: resolved.symbol for provider, resolved in matrix.items()},
+        notes="Inferred from symbol pattern. Verify exchange/provider entitlement before relying on it.",
+    )
+
+
 def _normalize(symbol: str) -> str:
     return symbol.strip().upper().replace(" ", "").replace("-", "").replace("_", "").replace("/", "")
 
@@ -180,3 +285,41 @@ def _alias_class(symbol: str) -> str:
     if symbol.startswith("XAU") or symbol.startswith("XAG"):
         return "commodity"
     return "index"
+
+
+def _symbol_alias_to_result(item: SymbolAlias) -> SymbolSearchResult:
+    matrix = provider_symbol_matrix(item.symbol)
+    return SymbolSearchResult(
+        symbol=item.symbol,
+        name=item.name,
+        asset_class=item.asset_class,
+        exchange=item.exchange,
+        currency=item.currency,
+        provider_symbols={provider: resolved.symbol for provider, resolved in matrix.items()},
+        notes=item.notes,
+    )
+
+
+def _match_score(query: str, haystack: list[str]) -> int:
+    score = 0
+    for value in haystack:
+        if value == query:
+            score = max(score, 100)
+        elif value.startswith(query):
+            score = max(score, 80)
+        elif query in value:
+            score = max(score, 50)
+    return score
+
+
+def _infer_asset_class(symbol: str) -> str:
+    normalized = _normalize(symbol)
+    if _is_metal_pair(normalized):
+        return "commodity"
+    if _is_forex_pair(normalized):
+        return "forex"
+    if normalized.endswith("USDT") or normalized.endswith("USD") and normalized[:3] in {"BTC", "ETH", "SOL", "BNB"}:
+        return "crypto"
+    if normalized.startswith("^") or normalized in YFINANCE_ALIASES:
+        return "index"
+    return "stock"

package/fincli/app/providers/market/twelvedata_provider.py

@@ -1,167 +1,167 @@
-"""Twelve Data provider for multi-asset market data."""
-
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Any
-
-import httpx
-
-from fincli.app.providers.market.base import Candle, FundamentalSnapshot, NewsItem, ProviderStatus, Quote
-from fincli.app.providers.market.symbols import resolve_twelvedata_symbol
-from fincli.app.utils.errors import ProviderError, RateLimitError
-
-
-class TwelveDataProvider:
-    name = "twelvedata"
-
-    def __init__(
-        self,
-        api_key: str | None,
-        base_url: str = "https://api.twelvedata.com",
-        client: httpx.AsyncClient | None = None,
-    ) -> None:
-        self.api_key = api_key or ""
-        self.base_url = base_url.rstrip("/")
-        self._client = client
-
-    async def quote(self, symbol: str) -> Quote:
-        resolved = resolve_twelvedata_symbol(symbol)
-        data = await self._get("/quote", {"symbol": resolved.symbol})
-        price = _safe_float(data.get("close") or data.get("price"))
-        if price is None:
-            raise ProviderError(f"Twelve Data tidak mengembalikan quote valid untuk {symbol}.")
-        return Quote(
-            symbol=str(data.get("symbol") or resolved.symbol).upper(),
-            price=price,
-            currency=str(data.get("currency") or "USD"),
-            provider=self.name,
-            timestamp=_parse_datetime(data.get("datetime")) or datetime.now(),
-            status="realtime",
-        )
-
-    async def history(self, symbol: str, period: str = "6mo", interval: str = "1d") -> list[Candle]:
-        resolved = resolve_twelvedata_symbol(symbol)
-        data = await self._get(
-            "/time_series",
-            {
-                "symbol": resolved.symbol,
-                "interval": _interval_to_twelvedata(interval),
-                "outputsize": _period_to_outputsize(period, interval),
-                "timezone": "UTC",
-            },
-        )
-        values = data.get("values") if isinstance(data, dict) else None
-        if not isinstance(values, list) or not values:
-            message = data.get("message") if isinstance(data, dict) else None
-            raise ProviderError(f"Twelve Data OHLCV kosong untuk {symbol}.", str(message) if message else None)
-
-        candles = [_parse_candle(item) for item in values if isinstance(item, dict)]
-        candles.sort(key=lambda candle: candle.timestamp)
-        if not candles:
-            raise ProviderError(f"Twelve Data OHLCV kosong untuk {symbol}.")
-        return candles
-
-    async def news(self, symbol: str, limit: int = 5) -> list[NewsItem]:
-        return []
-
-    async def fundamentals(self, symbol: str) -> FundamentalSnapshot:
-        resolved = resolve_twelvedata_symbol(symbol)
-        return FundamentalSnapshot(symbol=resolved.symbol.upper(), provider=self.name, currency="USD")
-
-    async def status(self) -> ProviderStatus:
-        status = "configured" if self.api_key else "unavailable"
-        message = "Twelve Data provider configured." if self.api_key else "Requires TWELVE_DATA_API_KEY."
-        return ProviderStatus(name=self.name, realtime=True, status=status, message=message)
-
-    async def _get(self, path: str, params: dict[str, object]) -> Any:
-        if not self.api_key:
-            raise ProviderError("API key Twelve Data belum diatur.", "Gunakan /news_model key twelvedata <api_key>.")
-        close_client = self._client is None
-        client = self._client or httpx.AsyncClient(timeout=30)
-        try:
-            response = await client.get(f"{self.base_url}{path}", params={**params, "apikey": self.api_key})
-            if response.status_code == 429:
-                raise RateLimitError("Twelve Data terkena rate limit.")
-            response.raise_for_status()
-            data = response.json()
-            if isinstance(data, dict) and data.get("status") == "error":
-                raise ProviderError(f"Twelve Data gagal: {data.get('message') or 'unknown error'}")
-            return data
-        except httpx.TimeoutException as exc:
-            raise ProviderError("Twelve Data timeout.") from exc
-        except httpx.HTTPStatusError as exc:
-            raise ProviderError(f"Twelve Data gagal: HTTP {exc.response.status_code}.") from exc
-        except ValueError as exc:
-            raise ProviderError("Response Twelve Data bukan JSON valid.") from exc
-        finally:
-            if close_client:
-                await client.aclose()
-
-
-def _parse_candle(item: dict[str, Any]) -> Candle:
-    return Candle(
-        timestamp=_parse_datetime(item.get("datetime")) or datetime.now(),
-        open=float(item["open"]),
-        high=float(item["high"]),
-        low=float(item["low"]),
-        close=float(item["close"]),
-        volume=float(item.get("volume") or 0),
-    )
-
-
-def _safe_float(value: Any) -> float | None:
-    try:
-        if value is None:
-            return None
-        return float(value)
-    except (TypeError, ValueError):
-        return None
-
-
-def _parse_datetime(value: object) -> datetime | None:
-    if not value:
-        return None
-    text = str(value).replace("Z", "+00:00")
-    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d"):
-        try:
-            return datetime.strptime(text, fmt)
-        except ValueError:
-            continue
-    try:
-        return datetime.fromisoformat(text)
-    except ValueError:
-        return None
-
-
-def _interval_to_twelvedata(interval: str) -> str:
-    mapping = {
-        "1m": "1min",
-        "5m": "5min",
-        "15m": "15min",
-        "30m": "30min",
-        "1h": "1h",
-        "4h": "4h",
-        "1d": "1day",
-        "d": "1day",
-        "1w": "1week",
-        "w": "1week",
-        "1mo": "1month",
-    }
-    return mapping.get(interval.lower(), interval)
-
-
-def _period_to_outputsize(period: str, interval: str) -> int:
-    normalized = period.lower()
-    interval_normalized = interval.lower()
-    if normalized.endswith("mo"):
-        days = 30 * int(normalized[:-2] or 6)
-    elif normalized.endswith("y"):
-        days = 365 * int(normalized[:-1] or 1)
-    elif normalized.endswith("d"):
-        days = int(normalized[:-1] or 180)
-    else:
-        days = 180
-    if interval_normalized in {"1m", "5m", "15m", "30m", "1h", "4h"}:
-        return min(5000, max(120, days * 24))
-    return min(5000, max(30, days))
+"""Twelve Data provider for multi-asset market data."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from fincli.app.providers.market.base import Candle, FundamentalSnapshot, NewsItem, ProviderStatus, Quote
+from fincli.app.providers.market.symbols import resolve_twelvedata_symbol
+from fincli.app.utils.errors import ProviderError, RateLimitError
+
+
+class TwelveDataProvider:
+    name = "twelvedata"
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str = "https://api.twelvedata.com",
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = api_key or ""
+        self.base_url = base_url.rstrip("/")
+        self._client = client
+
+    async def quote(self, symbol: str) -> Quote:
+        resolved = resolve_twelvedata_symbol(symbol)
+        data = await self._get("/quote", {"symbol": resolved.symbol})
+        price = _safe_float(data.get("close") or data.get("price"))
+        if price is None:
+            raise ProviderError(f"Twelve Data tidak mengembalikan quote valid untuk {symbol}.")
+        return Quote(
+            symbol=str(data.get("symbol") or resolved.symbol).upper(),
+            price=price,
+            currency=str(data.get("currency") or "USD"),
+            provider=self.name,
+            timestamp=_parse_datetime(data.get("datetime")) or datetime.now(),
+            status="realtime",
+        )
+
+    async def history(self, symbol: str, period: str = "6mo", interval: str = "1d") -> list[Candle]:
+        resolved = resolve_twelvedata_symbol(symbol)
+        data = await self._get(
+            "/time_series",
+            {
+                "symbol": resolved.symbol,
+                "interval": _interval_to_twelvedata(interval),
+                "outputsize": _period_to_outputsize(period, interval),
+                "timezone": "UTC",
+            },
+        )
+        values = data.get("values") if isinstance(data, dict) else None
+        if not isinstance(values, list) or not values:
+            message = data.get("message") if isinstance(data, dict) else None
+            raise ProviderError(f"Twelve Data OHLCV kosong untuk {symbol}.", str(message) if message else None)
+
+        candles = [_parse_candle(item) for item in values if isinstance(item, dict)]
+        candles.sort(key=lambda candle: candle.timestamp)
+        if not candles:
+            raise ProviderError(f"Twelve Data OHLCV kosong untuk {symbol}.")
+        return candles
+
+    async def news(self, symbol: str, limit: int = 5) -> list[NewsItem]:
+        return []
+
+    async def fundamentals(self, symbol: str) -> FundamentalSnapshot:
+        resolved = resolve_twelvedata_symbol(symbol)
+        return FundamentalSnapshot(symbol=resolved.symbol.upper(), provider=self.name, currency="USD")
+
+    async def status(self) -> ProviderStatus:
+        status = "configured" if self.api_key else "unavailable"
+        message = "Twelve Data provider configured." if self.api_key else "Requires TWELVE_DATA_API_KEY."
+        return ProviderStatus(name=self.name, realtime=True, status=status, message=message)
+
+    async def _get(self, path: str, params: dict[str, object]) -> Any:
+        if not self.api_key:
+            raise ProviderError("API key Twelve Data belum diatur.", "Gunakan /news_model key twelvedata <api_key>.")
+        close_client = self._client is None
+        client = self._client or httpx.AsyncClient(timeout=30)
+        try:
+            response = await client.get(f"{self.base_url}{path}", params={**params, "apikey": self.api_key})
+            if response.status_code == 429:
+                raise RateLimitError("Twelve Data terkena rate limit.")
+            response.raise_for_status()
+            data = response.json()
+            if isinstance(data, dict) and data.get("status") == "error":
+                raise ProviderError(f"Twelve Data gagal: {data.get('message') or 'unknown error'}")
+            return data
+        except httpx.TimeoutException as exc:
+            raise ProviderError("Twelve Data timeout.") from exc
+        except httpx.HTTPStatusError as exc:
+            raise ProviderError(f"Twelve Data gagal: HTTP {exc.response.status_code}.") from exc
+        except ValueError as exc:
+            raise ProviderError("Response Twelve Data bukan JSON valid.") from exc
+        finally:
+            if close_client:
+                await client.aclose()
+
+
+def _parse_candle(item: dict[str, Any]) -> Candle:
+    return Candle(
+        timestamp=_parse_datetime(item.get("datetime")) or datetime.now(),
+        open=float(item["open"]),
+        high=float(item["high"]),
+        low=float(item["low"]),
+        close=float(item["close"]),
+        volume=float(item.get("volume") or 0),
+    )
+
+
+def _safe_float(value: Any) -> float | None:
+    try:
+        if value is None:
+            return None
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_datetime(value: object) -> datetime | None:
+    if not value:
+        return None
+    text = str(value).replace("Z", "+00:00")
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(text, fmt)
+        except ValueError:
+            continue
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError:
+        return None
+
+
+def _interval_to_twelvedata(interval: str) -> str:
+    mapping = {
+        "1m": "1min",
+        "5m": "5min",
+        "15m": "15min",
+        "30m": "30min",
+        "1h": "1h",
+        "4h": "4h",
+        "1d": "1day",
+        "d": "1day",
+        "1w": "1week",
+        "w": "1week",
+        "1mo": "1month",
+    }
+    return mapping.get(interval.lower(), interval)
+
+
+def _period_to_outputsize(period: str, interval: str) -> int:
+    normalized = period.lower()
+    interval_normalized = interval.lower()
+    if normalized.endswith("mo"):
+        days = 30 * int(normalized[:-2] or 6)
+    elif normalized.endswith("y"):
+        days = 365 * int(normalized[:-1] or 1)
+    elif normalized.endswith("d"):
+        days = int(normalized[:-1] or 180)
+    else:
+        days = 180
+    if interval_normalized in {"1m", "5m", "15m", "30m", "1h", "4h"}:
+        return min(5000, max(120, days * 24))
+    return min(5000, max(30, days))

package/fincli/app/providers/market/yfinance_provider.py

@@ -1,4 +1,4 @@
-"""yfinance fallback provider placeholder for Phase 2."""
+"""yfinance fallback provider for delayed public market data."""
 
 import asyncio
 from dataclasses import dataclass

package/fincli/app/research/__init__.py

@@ -0,0 +1,7 @@
+"""Research workspace package."""
+
+from fincli.app.research.engine import ResearchEngine
+from fincli.app.research.formatter import format_research_brief
+from fincli.app.research.models import ResearchBrief
+
+__all__ = ["ResearchBrief", "ResearchEngine", "format_research_brief"]

package/fincli/app/research/engine.py

@@ -0,0 +1,75 @@
+"""Research workspace orchestration."""
+
+from __future__ import annotations
+
+from fincli.app.providers.ai.base import AIRequest, BaseAIProvider
+from fincli.app.research.models import ResearchBrief
+from fincli.app.research.prompt_builder import build_research_prompt
+from fincli.app.services.market_data import MarketDataService
+from fincli.app.services.market_overview import MarketOverview, build_market_overview
+
+
+class ResearchEngine:
+    """Build compact research briefs around the existing market overview service."""
+
+    def __init__(self, market_service: MarketDataService, ai_provider: BaseAIProvider | None = None, model: str = "") -> None:
+        self.market_service = market_service
+        self.ai_provider = ai_provider
+        self.model = model
+
+    async def build(self, symbol: str, timeframe: str = "1d", mode: str = "quick") -> ResearchBrief:
+        overview = await build_market_overview(symbol.upper(), self.market_service, timeframe)
+        brief = _brief_from_overview(overview, mode)
+        if mode == "deep" and self.ai_provider is not None:
+            prompt = build_research_prompt(brief)
+            response = await self.ai_provider.complete(AIRequest(prompt=prompt, model=self.model))
+            return ResearchBrief(
+                symbol=brief.symbol,
+                mode=brief.mode,
+                overview=brief.overview,
+                decision_points=brief.decision_points,
+                risks=brief.risks,
+                final_summary=brief.final_summary,
+                ai_summary=response.content,
+            )
+        return brief
+
+
+def _brief_from_overview(overview: MarketOverview, mode: str) -> ResearchBrief:
+    technical = overview.technical
+    structure = overview.structure
+    fundamentals = overview.fundamentals
+    decision_points = [
+        f"Price {overview.quote.price} {overview.quote.currency} via {overview.quote.provider} ({overview.quote.status}).",
+        f"Trend bias {technical.trend_bias}; structure {structure.trend} with {structure.latest_pattern}.",
+        f"Key levels: support {technical.support}, resistance {technical.resistance}, ATR {technical.atr}.",
+        f"Momentum: RSI {technical.rsi}, MACD {technical.macd}/{technical.macd_signal}.",
+    ]
+    if fundamentals is not None:
+        decision_points.append(
+            f"Fundamentals: P/E {fundamentals.pe_ratio}, EPS {fundamentals.eps}, sector {fundamentals.sector or 'N/A'}."
+        )
+    if overview.news:
+        decision_points.append(f"Latest news: {overview.news[0].title} ({overview.news[0].source}).")
+
+    risks = [
+        f"Data quality {overview.data_quality.score}/100; provider label {overview.data_quality.provider}.",
+        "Use confirmation and invalidation; do not treat this brief as financial advice.",
+    ]
+    if structure.change_of_character:
+        risks.append("Change of character detected; directional confidence should be reduced.")
+    if technical.rsi is not None and (technical.rsi > 75 or technical.rsi < 25):
+        risks.append("RSI is at an extreme; avoid chasing without confirmation.")
+
+    final_summary = (
+        f"{overview.symbol} is a {technical.trend_bias} / {structure.trend} setup with "
+        f"{overview.data_quality.score}/100 data quality. Focus on support/resistance reaction and news/fundamental confirmation."
+    )
+    return ResearchBrief(
+        symbol=overview.symbol,
+        mode=mode,
+        overview=overview,
+        decision_points=decision_points[:6],
+        risks=risks[:4],
+        final_summary=final_summary,
+    )

package/fincli/app/research/formatter.py

@@ -0,0 +1,22 @@
+"""Rich renderers for research workspace."""
+
+from __future__ import annotations
+
+from rich.table import Table
+
+from fincli.app.research.models import ResearchBrief
+from fincli.app.utils.formatting import semantic_text
+
+
+def format_research_brief(brief: ResearchBrief) -> Table:
+    table = Table(title=f"Research Brief: {brief.symbol} | {brief.mode}", expand=True)
+    table.add_column("Section", style="cyan", no_wrap=True)
+    table.add_column("Description", overflow="fold")
+    table.add_row("Data Quality", semantic_text(f"{brief.overview.data_quality.score}/100 | {brief.overview.data_quality.provider}"))
+    table.add_row("Decision Points", semantic_text("\n".join(f"- {point}" for point in brief.decision_points)))
+    table.add_row("Risks", semantic_text("\n".join(f"- {risk}" for risk in brief.risks)))
+    if brief.ai_summary:
+        table.add_row("AI Summary", brief.ai_summary)
+    table.add_row("Final Summary", semantic_text(brief.final_summary))
+    table.caption = "Research output is informational only, not financial advice."
+    return table

package/fincli/app/research/models.py

@@ -0,0 +1,18 @@
+"""Models for FinCLI research workspace."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fincli.app.services.market_overview import MarketOverview
+
+
+@dataclass(frozen=True, slots=True)
+class ResearchBrief:
+    symbol: str
+    mode: str
+    overview: MarketOverview
+    decision_points: list[str]
+    risks: list[str]
+    final_summary: str
+    ai_summary: str = ""