@drico2008/fincli 0.1.9 → 0.3.0

package/fincli/app/research/engine.py

@@ -0,0 +1,137 @@
+"""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,
+                snapshot=brief.snapshot,
+                signal=brief.signal,
+                risk=brief.risk,
+                missing_data=brief.missing_data,
+                source_quality=brief.source_quality,
+                decision_points=brief.decision_points,
+                risks=brief.risks,
+                final_summary=brief.final_summary,
+                ai_summary=response.content,
+                report_notes=brief.report_notes,
+            )
+        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}).")
+
+    missing_data = ", ".join(overview.data_quality.missing_fields) if overview.data_quality.missing_fields else "none"
+    source_quality = (
+        f"{overview.data_quality.score}/100 | reliability={overview.data_quality.reliability_status} | "
+        f"provider={overview.data_quality.provider}"
+    )
+    signal = _research_signal(overview)
+    risk = _research_risk(overview)
+    snapshot = (
+        f"{overview.symbol}: {technical.trend_bias} trend, {structure.trend} structure, "
+        f"price {overview.quote.price} {overview.quote.currency}, data {overview.data_quality.score}/100."
+    )
+
+    risks = [
+        f"Source quality: {source_quality}.",
+        "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 = _final_summary(overview, signal, risk, missing_data)
+    report_notes = (
+        f"Snapshot: {snapshot}",
+        f"Signal: {signal}",
+        f"Risk: {risk}",
+        f"Missing data: {missing_data}",
+        f"Source quality: {source_quality}",
+        "Not financial advice.",
+    )
+    return ResearchBrief(
+        symbol=overview.symbol,
+        mode=mode,
+        overview=overview,
+        snapshot=snapshot,
+        signal=signal,
+        risk=risk,
+        missing_data=missing_data,
+        source_quality=source_quality,
+        decision_points=decision_points[:6],
+        risks=risks[:4],
+        final_summary=final_summary,
+        report_notes=report_notes,
+    )
+
+
+def _research_signal(overview: MarketOverview) -> str:
+    trend = overview.technical.trend_bias.lower()
+    structure = overview.structure.trend.lower()
+    rsi = overview.technical.rsi
+    if overview.data_quality.reliability_status != "ok":
+        return "CAUTION - data incomplete; verify provider source first."
+    if trend == "bullish" and structure == "bullish" and (rsi is None or rsi < 75):
+        return "BULLISH WATCH - only after support/retest confirmation."
+    if trend == "bearish" and structure == "bearish" and (rsi is None or rsi > 25):
+        return "BEARISH WATCH - only after resistance/rejection confirmation."
+    return "CAUTION - mixed or extended setup; wait for confirmation."
+
+
+def _research_risk(overview: MarketOverview) -> str:
+    risks: list[str] = []
+    if overview.structure.change_of_character:
+        risks.append("CHoCH detected")
+    if overview.technical.rsi is not None and overview.technical.rsi > 75:
+        risks.append("RSI overbought")
+    if overview.technical.rsi is not None and overview.technical.rsi < 25:
+        risks.append("RSI oversold")
+    if overview.data_quality.missing_fields:
+        risks.append(f"missing {', '.join(overview.data_quality.missing_fields)}")
+    return "; ".join(risks) if risks else "standard market risk; define invalidation before entry"
+
+
+def _final_summary(overview: MarketOverview, signal: str, risk: str, missing_data: str) -> str:
+    return (
+        f"{overview.symbol}: {signal}. Key risk: {risk}. "
+        f"Missing data: {missing_data}. Treat this as research context, not financial advice."
+    )

package/fincli/app/research/exporter.py

@@ -0,0 +1,91 @@
+"""Export helpers for Research Engine v2 reports."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from fincli.app.research.models import ResearchBrief
+from fincli.app.utils.errors import CommandError
+
+
+def write_research_report(brief: ResearchBrief, fmt: str, target: str | Path) -> Path:
+    report_format = fmt.lower()
+    path = _safe_research_path(target, report_format)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if report_format == "json":
+        path.write_text(json.dumps(_research_payload(brief), indent=2, default=str), encoding="utf-8")
+        return path
+    if report_format in {"md", "markdown"}:
+        path.write_text(_research_markdown(brief), encoding="utf-8")
+        return path
+    raise CommandError("Research export format harus md atau json.")
+
+
+def _safe_research_path(target: str | Path, fmt: str) -> Path:
+    path = Path(target).expanduser()
+    if any(part == ".." for part in path.parts):
+        raise CommandError("Research export path tidak boleh mengandung '..'.")
+    allowed = {".md", ".json"} if fmt in {"md", "markdown", "json"} else set()
+    if path.suffix.lower() not in allowed:
+        raise CommandError("Research export path harus berakhir .md atau .json.")
+    return path
+
+
+def _research_payload(brief: ResearchBrief) -> dict[str, Any]:
+    return {
+        "symbol": brief.symbol,
+        "mode": brief.mode,
+        "snapshot": brief.snapshot,
+        "signal": brief.signal,
+        "risk": brief.risk,
+        "missing_data": brief.missing_data,
+        "source_quality": brief.source_quality,
+        "decision_points": brief.decision_points,
+        "risks": brief.risks,
+        "final_summary": brief.final_summary,
+        "ai_summary": brief.ai_summary,
+        "report_notes": list(brief.report_notes),
+        "disclaimer": "Not financial advice.",
+    }
+
+
+def _research_markdown(brief: ResearchBrief) -> str:
+    notes = "\n".join(f"- {item}" for item in brief.report_notes)
+    points = "\n".join(f"- {item}" for item in brief.decision_points)
+    risks = "\n".join(f"- {item}" for item in brief.risks)
+    return "\n".join(
+        [
+            f"# FinCLI Research Report: {brief.symbol}",
+            "",
+            f"- Mode: {brief.mode}",
+            f"- Snapshot: {brief.snapshot}",
+            f"- Signal: {brief.signal}",
+            f"- Risk: {brief.risk}",
+            f"- Missing Data: {brief.missing_data}",
+            f"- Source Quality: {brief.source_quality}",
+            "",
+            "## Decision Points",
+            "",
+            points or "- None.",
+            "",
+            "## Risk Notes",
+            "",
+            risks or "- None.",
+            "",
+            "## Report Notes",
+            "",
+            notes or "- None.",
+            "",
+            "## Final Summary",
+            "",
+            brief.final_summary,
+            "",
+            "## Disclaimer",
+            "",
+            "Not financial advice.",
+            "",
+        ]
+    )
+

package/fincli/app/research/formatter.py

@@ -0,0 +1,27 @@
+"""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 Center: {brief.symbol} | {brief.mode} | Research Brief v2", expand=True)
+    table.add_column("Section", style="cyan", no_wrap=True)
+    table.add_column("Description", overflow="fold")
+    table.add_row("Snapshot", semantic_text(brief.snapshot))
+    table.add_row("Signal", semantic_text(brief.signal))
+    table.add_row("Risk", semantic_text(brief.risk))
+    table.add_row("Missing Data", semantic_text(brief.missing_data))
+    table.add_row("Source Quality", semantic_text(brief.source_quality))
+    table.add_row("Decision Points", semantic_text(" | ".join(brief.decision_points[:2])))
+    if brief.mode == "report":
+        table.add_row("Report Notes", semantic_text("\n".join(f"- {item}" for item in brief.report_notes)))
+    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,24 @@
+"""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
+    snapshot: str
+    signal: str
+    risk: str
+    missing_data: str
+    source_quality: str
+    decision_points: list[str]
+    risks: list[str]
+    final_summary: str
+    ai_summary: str = ""
+    report_notes: tuple[str, ...] = ()

package/fincli/app/research/prompt_builder.py

@@ -0,0 +1,54 @@
+"""Prompt builder for deep research mode."""
+
+from __future__ import annotations
+
+from fincli.app.research.models import ResearchBrief
+
+
+RESEARCH_WORKSPACE_PROMPT = """
+You are FinCLI Research Workspace, operating as Research Engine v2.
+
+Rules:
+- Build a concise investment/trading research note from the provided data only.
+- Output must focus on snapshot, signal, risk, missing data, source quality.
+- Do not invent price, news, fundamentals, or certainty.
+- Do not copy the opening summary as the final summary.
+- Prioritize decision-useful points over long explanation.
+- Separate facts, interpretation, and risk.
+- Keep output short: max 8 bullets plus final summary.
+- Use slash-command context correctly: FinCLI commands start with "/", not "fincli".
+- This is educational market research, not financial advice.
+""".strip()
+
+
+def build_research_prompt(brief: ResearchBrief) -> str:
+    overview = brief.overview
+    news = "\n".join(f"- {item.title} ({item.source}) {item.summary}" for item in overview.news) or "- No news."
+    fundamentals = overview.fundamentals
+    fundamentals_text = (
+        "No fundamentals."
+        if fundamentals is None
+        else (
+            f"market_cap={fundamentals.market_cap}; pe={fundamentals.pe_ratio}; eps={fundamentals.eps}; "
+            f"revenue={fundamentals.revenue}; sector={fundamentals.sector}; industry={fundamentals.industry}"
+        )
+    )
+    return (
+        f"{RESEARCH_WORKSPACE_PROMPT}\n\n"
+        f"Symbol: {brief.symbol}\n"
+        f"Mode: {brief.mode}\n"
+        "Required focus: snapshot, signal, risk, missing data, source quality.\n"
+        f"Snapshot: {brief.snapshot}\n"
+        f"Signal: {brief.signal}\n"
+        f"Risk: {brief.risk}\n"
+        f"Missing Data: {brief.missing_data}\n"
+        f"Source Quality: {brief.source_quality}\n"
+        f"Quote: {overview.quote.price} {overview.quote.currency} via {overview.quote.provider} ({overview.quote.status})\n"
+        f"Data Quality: {overview.data_quality.score}/100; OHLCV={overview.data_quality.ohlcv}; News={overview.data_quality.news}; Fundamentals={overview.data_quality.fundamentals}\n"
+        f"Technical: trend={overview.technical.trend_bias}; rsi={overview.technical.rsi}; macd={overview.technical.macd}; support={overview.technical.support}; resistance={overview.technical.resistance}; atr={overview.technical.atr}\n"
+        f"Structure: trend={overview.structure.trend}; pattern={overview.structure.latest_pattern}; bos={overview.structure.break_of_structure}; choch={overview.structure.change_of_character}\n"
+        f"Decision Points:\n{chr(10).join(f'- {point}' for point in brief.decision_points)}\n"
+        f"Risks:\n{chr(10).join(f'- {risk}' for risk in brief.risks)}\n"
+        f"News:\n{news}\n"
+        f"Fundamentals: {fundamentals_text}\n"
+    )

package/fincli/app/services/macro_data.py

@@ -0,0 +1,50 @@
+"""Macro data service with offline-first fallback rows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+
+
+@dataclass(frozen=True, slots=True)
+class MacroIndicator:
+    name: str
+    region: str
+    value: str
+    period: str
+    source: str
+    note: str
+
+
+class MacroDataService:
+    """Return macro context from free fallback datasets.
+
+    v0.3.0 keeps this deterministic/offline so /macro remains usable without API keys.
+    Provider-backed DBnomics/FRED/World Bank adapters can hydrate this shape later.
+    """
+
+    def indicators(self, query: str = "") -> list[MacroIndicator]:
+        normalized = query.strip().lower()
+        rows = _fallback_rows()
+        if not normalized:
+            return rows
+        filtered = [
+            row
+            for row in rows
+            if normalized in row.region.lower()
+            or normalized in row.name.lower()
+            or normalized in row.note.lower()
+        ]
+        return filtered or rows[:5]
+
+
+def _fallback_rows() -> list[MacroIndicator]:
+    period = date.today().strftime("%Y")
+    return [
+        MacroIndicator("Policy Rate", "United States", "provider required", period, "Fallback", "Watch FRED/Fed data for rate path."),
+        MacroIndicator("Inflation", "United States", "provider required", period, "Fallback", "CPI trend drives USD, yields, and risk assets."),
+        MacroIndicator("GDP Growth", "World", "provider required", period, "Fallback", "Use World Bank/IMF for actual country values."),
+        MacroIndicator("Policy Rate", "Indonesia", "provider required", period, "Fallback", "BI rate, USD strength, and capital flow affect IDR."),
+        MacroIndicator("Inflation", "Indonesia", "provider required", period, "Fallback", "Inflation surprise can affect BI policy expectations."),
+        MacroIndicator("PMI", "Euro Area", "provider required", period, "Fallback", "Growth momentum proxy for EUR and European equities."),
+    ]