@drico2008/fincli 0.3.1 → 0.4.0

package/fincli/app/providers/reliability.py

@@ -1,86 +1,103 @@
-"""Provider reliability contracts and status classification."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-
-from fincli.app.utils.errors import RateLimitError
-
-
-STATUS_OK = "ok"
-STATUS_AUTH_FAILED = "auth_failed"
-STATUS_RATE_LIMITED = "rate_limited"
+"""Provider reliability contracts and status classification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fincli.app.utils.errors import RateLimitError
+
+
+STATUS_OK = "ok"
+STATUS_AUTH_FAILED = "auth_failed"
+STATUS_RATE_LIMITED = "rate_limited"
 STATUS_ENTITLEMENT_MISSING = "entitlement_missing"
 STATUS_PARTIAL_DATA = "partial_data"
+STATUS_EMPTY_DATA = "empty_data"
+STATUS_NETWORK_ERROR = "network_error"
 STATUS_SCHEDULE_ONLY = "schedule_only"
 STATUS_UNAVAILABLE = "unavailable"
-
-GRANULAR_STATUSES = (
-    STATUS_OK,
-    STATUS_AUTH_FAILED,
-    STATUS_RATE_LIMITED,
+STATUS_CIRCUIT_OPEN = "circuit_open"
+
+GRANULAR_STATUSES = (
+    STATUS_OK,
+    STATUS_AUTH_FAILED,
+    STATUS_RATE_LIMITED,
     STATUS_ENTITLEMENT_MISSING,
     STATUS_PARTIAL_DATA,
+    STATUS_EMPTY_DATA,
+    STATUS_NETWORK_ERROR,
     STATUS_SCHEDULE_ONLY,
     STATUS_UNAVAILABLE,
+    STATUS_CIRCUIT_OPEN,
 )
-
-
-@dataclass(frozen=True, slots=True)
-class ProviderResult:
-    """Standard result envelope for provider calls."""
-
-    provider: str
-    operation: str
-    status: str
-    realtime_label: str = "unknown"
-    source: str = ""
-    data_quality: str = "unknown"
-    missing_fields: tuple[str, ...] = ()
-    message: str = ""
-
-
-def classify_provider_error(exc: BaseException) -> str:
-    """Classify provider failures into stable user-facing reliability statuses."""
-    if isinstance(exc, RateLimitError):
-        return STATUS_RATE_LIMITED
-
-    text = f"{exc} {getattr(exc, 'help_text', '') or ''}".lower()
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderResult:
+    """Standard result envelope for provider calls."""
+
+    provider: str
+    operation: str
+    status: str
+    realtime_label: str = "unknown"
+    source: str = ""
+    data_quality: str = "unknown"
+    missing_fields: tuple[str, ...] = ()
+    message: str = ""
+
+
+def classify_provider_error(exc: BaseException) -> str:
+    """Classify provider failures into stable user-facing reliability statuses."""
+    if isinstance(exc, RateLimitError):
+        return STATUS_RATE_LIMITED
+
+    text = f"{exc} {getattr(exc, 'help_text', '') or ''}".lower()
     if "429" in text or "rate limit" in text or "too many request" in text:
         return STATUS_RATE_LIMITED
     if "401" in text or "unauthorized" in text or "invalid key" in text or "api key" in text and "belum" in text:
         return STATUS_AUTH_FAILED
     if "403" in text or "entitlement" in text or "plan" in text or "premium" in text or "forbidden" in text:
         return STATUS_ENTITLEMENT_MISSING
-    if "empty" in text or "kosong" in text or "no data" in text or "missing" in text:
+    if "timeout" in text or "timed out" in text or "network" in text or "connection" in text or "dns" in text:
+        return STATUS_NETWORK_ERROR
+    if "empty" in text or "kosong" in text or "no data" in text:
+        return STATUS_EMPTY_DATA
+    if "missing" in text:
         return STATUS_PARTIAL_DATA
     return STATUS_UNAVAILABLE
-
-
-def classify_payload(operation: str, payload: Any) -> tuple[str, tuple[str, ...]]:
-    """Classify successful provider payload completeness."""
+
+
+def classify_payload(operation: str, payload: Any) -> tuple[str, tuple[str, ...]]:
+    """Classify successful provider payload completeness."""
     if payload is None:
-        return STATUS_PARTIAL_DATA, (operation,)
+        return STATUS_EMPTY_DATA, (operation,)
     if isinstance(payload, list) and not payload:
-        return STATUS_PARTIAL_DATA, (operation,)
-    if operation == "quote" and getattr(payload, "price", None) is None:
-        return STATUS_PARTIAL_DATA, ("price",)
-    if operation == "fundamentals":
-        missing = tuple(
-            field
-            for field in ("market_cap", "pe_ratio", "eps", "revenue", "sector", "industry")
-            if getattr(payload, field, None) in (None, "")
-        )
-        return (STATUS_PARTIAL_DATA if missing else STATUS_OK), missing
-    return STATUS_OK, ()
-
-
-def result_style(status: str) -> str:
-    """Return a Rich style name for reliability statuses."""
-    if status == STATUS_OK:
-        return "green"
-    if status in {STATUS_AUTH_FAILED, STATUS_RATE_LIMITED, STATUS_ENTITLEMENT_MISSING, STATUS_UNAVAILABLE}:
+        return STATUS_EMPTY_DATA, (operation,)
+    if operation == "quote" and getattr(payload, "price", None) is None:
+        return STATUS_PARTIAL_DATA, ("price",)
+    if operation == "fundamentals":
+        missing = tuple(
+            field
+            for field in ("market_cap", "pe_ratio", "eps", "revenue", "sector", "industry")
+            if getattr(payload, field, None) in (None, "")
+        )
+        return (STATUS_PARTIAL_DATA if missing else STATUS_OK), missing
+    return STATUS_OK, ()
+
+
+def result_style(status: str) -> str:
+    """Return a Rich style name for reliability statuses."""
+    if status == STATUS_OK:
+        return "green"
+    if status in {
+        STATUS_AUTH_FAILED,
+        STATUS_RATE_LIMITED,
+        STATUS_ENTITLEMENT_MISSING,
+        STATUS_UNAVAILABLE,
+        STATUS_NETWORK_ERROR,
+        STATUS_CIRCUIT_OPEN,
+    }:
         return "red"
     return "yellow"
-
+

package/fincli/app/research/__init__.py

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

package/fincli/app/research/engine.py

@@ -1,137 +1,144 @@
-"""Research workspace orchestration."""
-
-from __future__ import annotations
-
-from fincli.app.providers.ai.base import AIRequest, BaseAIProvider
+"""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.data_trust import build_data_trust_gate
 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:
+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)
+        brief = _brief_from_overview(overview, mode, self.market_service.provider_metrics_snapshot())
         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,
+            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,
+                trust_gate=brief.trust_gate,
                 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:
+                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, provider_metrics: dict[str, object] | None = None) -> 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 = [
+    trust_gate = build_data_trust_gate(overview.data_quality, provider_metrics)
+    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, trust_gate.level)
+    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}.",
+        f"Trust gate: {trust_gate.compact()}.",
         "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,
+    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,
+        trust_gate=trust_gate.compact(),
         decision_points=decision_points[:6],
-        risks=risks[:4],
-        final_summary=final_summary,
-        report_notes=report_notes,
-    )
-
-
-def _research_signal(overview: MarketOverview) -> str:
+        risks=risks[:4],
+        final_summary=final_summary,
+        report_notes=report_notes,
+    )
+
+
+def _research_signal(overview: MarketOverview, trust_level: str = "usable") -> str:
     trend = overview.technical.trend_bias.lower()
     structure = overview.structure.trend.lower()
     rsi = overview.technical.rsi
+    if trust_level in {"blocked", "limited"}:
+        return "CAUTION - data trust gate prevents directional signal; verify provider data first."
     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."
-    )
+    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

@@ -1,91 +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.",
-            "",
-        ]
-    )
-
+"""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.",
+            "",
+        ]
+    )
+