@drico2008/fincli 0.3.1 → 0.4.0

package/fincli/app/research/formatter.py

@@ -1,27 +1,28 @@
-"""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))
+"""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("Trust Gate", semantic_text(brief.trust_gate))
     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
+    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

@@ -1,24 +1,25 @@
-"""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
+"""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, ...] = ()
+    trust_gate: 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

@@ -1,54 +1,56 @@
-"""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.
+"""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"
+- Obey the Data Trust Gate. If it says caution/no directional signal, do not produce buy/sell conviction.
+- 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"Data Trust Gate: {brief.trust_gate}\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"
-    )
+        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/data_quality.py

@@ -0,0 +1,27 @@
+"""Standard data quality report model for FinCLI outputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class DataQualityReport:
+    score: int
+    quote: str
+    ohlcv: str
+    news: str
+    fundamentals: str
+    provider: str
+    tier: str
+    freshness: str
+    reliability_status: str
+    missing_fields: tuple[str, ...]
+    label: str
+
+    def compact(self) -> str:
+        missing = ", ".join(self.missing_fields) if self.missing_fields else "none"
+        return (
+            f"{self.score}/100 | tier={self.tier} | reliability={self.reliability_status} | "
+            f"freshness={self.freshness} | missing={missing}"
+        )

package/fincli/app/services/data_trust.py

@@ -0,0 +1,117 @@
+"""Data trust policy for AI/research outputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fincli.app.providers.reliability import STATUS_OK, STATUS_PARTIAL_DATA, STATUS_UNAVAILABLE
+from fincli.app.services.data_quality import DataQualityReport
+
+
+@dataclass(frozen=True, slots=True)
+class DataTrustGate:
+    level: str
+    action: str
+    confidence_cap: int
+    max_signal_strength: str
+    reasons: tuple[str, ...]
+    required_verification: tuple[str, ...]
+
+    def compact(self) -> str:
+        reasons = "; ".join(self.reasons) if self.reasons else "none"
+        verify = "; ".join(self.required_verification) if self.required_verification else "none"
+        return (
+            f"level={self.level} | action={self.action} | confidence_cap={self.confidence_cap}% | "
+            f"max_signal={self.max_signal_strength} | reasons={reasons} | verify={verify}"
+        )
+
+    def prompt_context(self) -> str:
+        return (
+            "Data Trust Gate:\n"
+            f"- Trust Level: {self.level}\n"
+            f"- AI Action: {self.action}\n"
+            f"- Confidence Cap: {self.confidence_cap}%\n"
+            f"- Max Signal Strength: {self.max_signal_strength}\n"
+            f"- Reasons: {', '.join(self.reasons) if self.reasons else 'none'}\n"
+            f"- Required Verification: {', '.join(self.required_verification) if self.required_verification else 'none'}"
+        )
+
+
+def build_data_trust_gate(
+    quality: DataQualityReport,
+    provider_metrics: dict[str, Any] | None = None,
+) -> DataTrustGate:
+    """Convert data quality and provider runtime metrics into an AI confidence policy."""
+    reasons: list[str] = []
+    verify: list[str] = []
+    metrics = provider_metrics or {}
+
+    if quality.reliability_status == STATUS_UNAVAILABLE or "quote" in quality.missing_fields or "ohlcv" in quality.missing_fields:
+        reasons.append(f"critical market data unavailable: {quality.compact()}")
+        verify.extend(("quote availability", "OHLCV history availability", "provider entitlement"))
+        return DataTrustGate(
+            level="blocked",
+            action="no_directional_signal",
+            confidence_cap=20,
+            max_signal_strength="caution only",
+            reasons=tuple(reasons),
+            required_verification=tuple(verify),
+        )
+
+    if quality.reliability_status == STATUS_PARTIAL_DATA or quality.score < 65 or quality.missing_fields:
+        reasons.append(f"partial data quality: {quality.compact()}")
+        if quality.missing_fields:
+            verify.append("missing data: " + ", ".join(quality.missing_fields))
+
+    weak_metrics = _weak_metric_reasons(metrics)
+    reasons.extend(weak_metrics)
+    if weak_metrics:
+        verify.append("provider reliability/fallback chain")
+
+    if quality.score >= 85 and quality.reliability_status == STATUS_OK and not weak_metrics:
+        return DataTrustGate(
+            level="strong",
+            action="normal_scenario_analysis",
+            confidence_cap=80,
+            max_signal_strength="candidate buy/sell allowed with confirmation",
+            reasons=tuple(reasons),
+            required_verification=tuple(verify),
+        )
+
+    if quality.score >= 65 and quality.reliability_status == STATUS_OK and len(weak_metrics) <= 1:
+        return DataTrustGate(
+            level="usable",
+            action="moderated_scenario_analysis",
+            confidence_cap=60,
+            max_signal_strength="watchlist bias only",
+            reasons=tuple(reasons),
+            required_verification=tuple(verify),
+        )
+
+    return DataTrustGate(
+        level="limited",
+        action="caution_first_analysis",
+        confidence_cap=45,
+        max_signal_strength="caution or wait-for-confirmation only",
+        reasons=tuple(reasons) or (f"data quality below production threshold: {quality.compact()}",),
+        required_verification=tuple(verify) or ("provider data quality",),
+    )
+
+
+def _weak_metric_reasons(provider_metrics: dict[str, Any]) -> list[str]:
+    reasons: list[str] = []
+    for provider, metric in provider_metrics.items():
+        calls = int(getattr(metric, "calls", 0))
+        if calls <= 0:
+            continue
+        success_rate = float(getattr(metric, "success_rate", 0.0))
+        errors = int(getattr(metric, "errors", 0))
+        fallbacks = int(getattr(metric, "fallbacks", 0))
+        if calls >= 2 and success_rate < 50:
+            reasons.append(f"{provider} success rate weak ({success_rate:.1f}% over {calls} calls)")
+        if errors >= 2:
+            reasons.append(f"{provider} returned {errors} error(s)")
+        if fallbacks >= 2:
+            reasons.append(f"{provider} needed {fallbacks} fallback(s)")
+    return reasons

package/fincli/app/services/macro_data.py

@@ -1,50 +1,158 @@
-"""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.1 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."),
-    ]
+"""Macro data service with offline-first fallback rows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+import os
+from typing import Any, Awaitable
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+
+import httpx
+
+from fincli.app.utils.errors import ProviderError, RateLimitError
+
+
+@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.4.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 alpha_vantage_indicator(self, indicator: str, region: str = "us") -> list[MacroIndicator]:
+        service = AlphaVantageEconomicService(api_key=os.getenv("ALPHA_VANTAGE_API_KEY"))
+        return service.run(service.indicator(indicator, region))
+
+
+class AlphaVantageEconomicService:
+    """Fetch no-frills US macro indicators from Alpha Vantage economic endpoints."""
+
+    FUNCTIONS = {
+        "cpi": ("CPI", "monthly", "CPI"),
+        "inflation": ("INFLATION", "annual", "Inflation"),
+        "unemployment": ("UNEMPLOYMENT", "monthly", "Unemployment"),
+        "nfp": ("NONFARM_PAYROLL", "monthly", "Nonfarm Payroll"),
+        "nonfarm_payroll": ("NONFARM_PAYROLL", "monthly", "Nonfarm Payroll"),
+        "fed_funds": ("FEDERAL_FUNDS_RATE", "monthly", "Federal Funds Rate"),
+        "federal_funds_rate": ("FEDERAL_FUNDS_RATE", "monthly", "Federal Funds Rate"),
+        "gdp": ("REAL_GDP", "annual", "Real GDP"),
+        "real_gdp": ("REAL_GDP", "annual", "Real GDP"),
+        "gdp_per_capita": ("REAL_GDP_PER_CAPITA", "annual", "Real GDP Per Capita"),
+        "real_gdp_per_capita": ("REAL_GDP_PER_CAPITA", "annual", "Real GDP Per Capita"),
+    }
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str = "https://www.alphavantage.co/query",
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = api_key or ""
+        self.base_url = base_url
+        self._client = client
+
+    async def indicator(self, indicator: str, region: str = "us") -> list[MacroIndicator]:
+        normalized_region = region.strip().lower() or "us"
+        if normalized_region not in {"us", "usa", "united states"}:
+            raise ProviderError("Alpha Vantage macro endpoint FinCLI saat ini hanya mendukung region US.")
+        if not self.api_key:
+            raise ProviderError("ALPHA_VANTAGE_API_KEY belum diatur.", "Gunakan /news_model key alphavantage <api_key>.")
+        function, interval, label = self._function(indicator)
+
+        close_client = self._client is None
+        client = self._client or httpx.AsyncClient(timeout=30)
+        try:
+            response = await client.get(
+                self.base_url,
+                params={"function": function, "interval": interval, "apikey": self.api_key},
+            )
+            if response.status_code == 429:
+                raise RateLimitError("Alpha Vantage macro terkena rate limit.")
+            response.raise_for_status()
+            payload = response.json()
+        except httpx.TimeoutException as exc:
+            raise ProviderError("Alpha Vantage macro timeout.") from exc
+        except httpx.HTTPStatusError as exc:
+            raise ProviderError(f"Alpha Vantage macro gagal: HTTP {exc.response.status_code}.") from exc
+        except ValueError as exc:
+            raise ProviderError("Response Alpha Vantage macro bukan JSON valid.") from exc
+        finally:
+            if close_client:
+                await client.aclose()
+
+        if isinstance(payload, dict) and ("Error Message" in payload or "Information" in payload or "Note" in payload):
+            message = str(payload.get("Error Message") or payload.get("Information") or payload.get("Note"))
+            raise ProviderError(f"Alpha Vantage macro gagal: {message}")
+        rows = payload.get("data") if isinstance(payload, dict) else None
+        if not isinstance(rows, list) or not rows:
+            raise ProviderError("Alpha Vantage macro tidak mengembalikan data.")
+        result: list[MacroIndicator] = []
+        for row in rows[:12]:
+            if not isinstance(row, dict):
+                continue
+            period = str(row.get("date") or "-")
+            value = str(row.get("value") or "-")
+            result.append(
+                MacroIndicator(
+                    name=label,
+                    region="United States",
+                    value=value,
+                    period=period,
+                    source="Alpha Vantage",
+                    note=f"function={function}; interval={interval}",
+                )
+            )
+        return result
+
+    def run(self, awaitable: Awaitable[Any]) -> Any:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(awaitable)
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(asyncio.run, awaitable)
+            return future.result()
+
+    def _function(self, indicator: str) -> tuple[str, str, str]:
+        normalized = indicator.strip().lower().replace(" ", "_").replace("-", "_")
+        if normalized not in self.FUNCTIONS:
+            raise ProviderError("Macro indicator tidak dikenal.", "Gunakan /cpi us, /nfp us, /gdp us, /fed funds us.")
+        return self.FUNCTIONS[normalized]
+
+
+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."),
+    ]