@drico2008/fincli 0.3.1 → 0.4.0

package/README.md

@@ -1,217 +1,217 @@
-# FinCLI v0.3.0
-
-FinCLI is a modern financial CLI/TUI terminal for market research, technical analysis, AI-assisted analysis, provider management, portfolio risk, journaling, watchlists, and local-first financial workflows.
-
-FinCLI is an active MVP. Data quality depends on provider availability, API keys, provider plan entitlement, exchange coverage, and rate limits. yfinance remains the default delayed fallback.
-
-## Highlights
-
-- Textual + Rich terminal UI with slash commands.
-- Research-first workflow through `/research`.
-- Provider fallback chain with granular reliability labels: `ok`, `auth_failed`, `rate_limited`, `entitlement_missing`, `partial_data`, `schedule_only`, `unavailable`.
-- Provider metrics dashboard with runtime success rate, average latency, fallback count, and error count.
-- Persistent provider metrics in SQLite so `/provider metrics` can show current session and all-time call totals.
-- AI Grounding Guard for `/analyze`: AI prompts must consider data quality, provider reliability, missing data, and provider metrics before conclusions.
-- Market data adapters: yfinance, Finnhub, Twelve Data, Alpha Vantage, and custom provider schema.
-- 100+ news connector catalog with free RSS fallbacks and API-key-ready providers.
-- AI providers: OpenRouter, OpenAI, Groq, Together, HuggingFace, Gemini, Anthropic, and compatible HTTP providers.
-- Technical analysis: RSI, MACD, EMA/SMA, Bollinger Bands, ATR, support/resistance, market structure, and technical debate.
-- Portfolio Risk v3: exposure by asset class/currency, concentration risk, drawdown estimate, risk budget, realized/unrealized PnL, and portfolio health score.
-- Local-first storage: config, secrets, SQLite database, cache, sessions, watchlist, portfolio, journal, alerts.
-- Prepublish safety checks for secrets, runtime artifacts, and npm package manifest.
-
-## Install
-
-Local development:
-
-```bash
-python -m venv .venv
-.venv\Scripts\activate
-pip install -e ".[dev]"
-fincli
-```
-
-Global npm wrapper:
-
-```bash
-npm install -g @drico2008/fincli
-fincli
-```
-
-The npm wrapper requires Python 3.11+ on the user machine. It creates an isolated `.npm-python` environment inside the installed package.
-
-## API Key Setup
-
-Global users do not need to edit `.env`. Save keys from inside FinCLI:
-
-```text
-/ai_model key groq <api_key>
-/ai_model key openrouter <api_key>
-/news_model key finnhub <api_key>
-/news_model key twelvedata <api_key>
-/news_model key alphavantage <api_key>
-```
-
-Keys are stored locally in:
-
-```text
-~/.fincli/secrets.env
-```
-
-FinCLI masks keys in terminal output. Use `/secrets status`, `/secrets clear`, `/privacy status`, and `/privacy purge` for local security hygiene.
-
-## Core Commands
-
-Research and market:
-
-```text
-/research AAPL
-/research AAPL --deep
-/research AAPL --report
-/research AAPL --report --export md report.md
-/research AAPL --report --export json report.json
-/market AAPL 1d
-/news AAPL 7d
-/technical AAPL 1d
-/analyze AAPL 1d
-/mtf AAPL 1d,1h,15m
-/calendar week US high
-```
-
-Providers:
-
-```text
-/news_model
-/news_model list
-/news_model priority google_news_rss,yfinance,yahoo_finance_rss
-/provider status
-/provider metrics
-/provider list
-/provider entitlement
-/provider key status
-/provider test AAPL
-```
-
-Portfolio and risk:
-
-```text
-/portfolio
-/portfolio add AAPL 10 185
-/portfolio performance
-/portfolio risk
-/tx add buy AAPL 10 185
-/tx add sell AAPL 5 195
-```
-
-Workflow:
-
-```text
-/watchlist add AAPL
-/scan watchlist rsi<30
-/journal add AAPL bullish "Breakout failed, wait for confirmation"
-/journal stats
-/journal review
-/alert add AAPL above 200
-/history
-/cache stats
-/cache clear
-```
-
-Security and release:
-
-```text
-/secrets status
-/privacy status
-npm run prepublish:safety
-python scripts/prepublish_check.py
-```
-
-## Research Engine v2
-
-`/research` is the central research command. It returns a compact output:
-
-- Snapshot
-- Signal
-- Risk
-- Missing Data
-- Source Quality
-- Decision Points
-- Final Summary
-
-Deep mode sends a concise Research Engine v2 prompt to the active AI provider. Report mode adds report-oriented notes without creating another command surface.
-
-## Portfolio Risk v3
-
-`/portfolio risk` calculates:
-
-- Exposure by asset class
-- Currency exposure
-- Concentration risk
-- Drawdown estimate
-- Asset-class cap warning
-- Risk budget from `/profile`
-- Realized PnL
-- Unrealized PnL
-- Total PnL
-- Portfolio health score
-
-The health score is a local analytical score, not financial advice. It penalizes high concentration, missing prices, weak diversification, and drawdown.
-
-## Data Notes
-
-- yfinance is a delayed fallback and should not be described as realtime.
-- Finnhub, Twelve Data, Alpha Vantage, and other providers may require API keys, paid plans, and exchange entitlements.
-- Public RSS/news sources can change or fail without notice.
-- Calendar fallback may be `schedule_only` if actual provider data is unavailable.
-- AI output is informational and must not be treated as guaranteed signal or financial advice.
-
-## Local Storage
-
-FinCLI stores local data under:
-
-```text
-~/.fincli/config.json
-~/.fincli/secrets.env
-~/.fincli/fincli.db
-~/.fincli/fincli.log
-```
-
-Do not commit `.env`, local secrets, logs, databases, cache folders, or npm/python virtual environments.
-
-## Prepublish Safety
-
-Before publishing to npm or GitHub:
-
-```bash
-python -m pytest -q
-python -m compileall fincli tests scripts
-npm run check
-npm run prepublish:safety
-```
-
-The prepublish checker scans for `.env`, `secrets.env`, logs, SQLite databases, token-like strings, and unsafe `npm pack --dry-run` contents.
-
-## Roadmap
-
-### v0.3.x Hardening
-
-- Provider runtime metrics by provider started in `/provider metrics`.
-- Persistent provider metrics started in v0.3.0.
-- AI Grounding Guard started in `/analyze`.
-- Richer portfolio analytics: drawdown estimate and currency grouping started in Portfolio Risk v3.
-- Better research reports with Markdown/JSON export from `/research --report` started in v0.3.0.
-- Provider-specific schema validation for custom data APIs.
-- Improved AI grounding and citations for web/news-assisted answers.
-
-### v0.4
-
-- Strategy builder.
-- Alert daemon and notification integrations.
-- Backtesting with fees, slippage, and position sizing.
-- Optional cloud sync.
-- Plugin marketplace-style connector loading.
-- Realtime streaming where provider plans support it.
-
-## License
-
-MIT
+# FinCLI v0.4.0
+
+FinCLI is a modern financial CLI/TUI terminal for market research, technical analysis, AI-assisted analysis, provider management, portfolio risk, journaling, watchlists, and local-first financial workflows.
+
+FinCLI is an active MVP. Data quality depends on provider availability, API keys, provider plan entitlement, exchange coverage, and rate limits. yfinance remains the default delayed fallback.
+
+## Highlights
+
+- Textual + Rich terminal UI with slash commands.
+- Research-first workflow through `/research`.
+- Provider fallback chain with granular reliability labels: `ok`, `auth_failed`, `rate_limited`, `entitlement_missing`, `partial_data`, `schedule_only`, `unavailable`.
+- Provider metrics dashboard with runtime success rate, average latency, fallback count, and error count.
+- Persistent provider metrics in SQLite so `/provider metrics` can show current session and all-time call totals.
+- AI Grounding Guard for `/analyze`: AI prompts must consider data quality, provider reliability, missing data, and provider metrics before conclusions.
+- Market data adapters: yfinance, Finnhub, Twelve Data, Alpha Vantage, and custom provider schema.
+- 100+ news connector catalog with free RSS fallbacks and API-key-ready providers.
+- AI providers: OpenRouter, OpenAI, Groq, Together, HuggingFace, Gemini, Anthropic, and compatible HTTP providers.
+- Technical analysis: RSI, MACD, EMA/SMA, Bollinger Bands, ATR, support/resistance, market structure, and technical debate.
+- Portfolio Risk v3: exposure by asset class/currency, concentration risk, drawdown estimate, risk budget, realized/unrealized PnL, and portfolio health score.
+- Local-first storage: config, secrets, SQLite database, cache, sessions, watchlist, portfolio, journal, alerts.
+- Prepublish safety checks for secrets, runtime artifacts, and npm package manifest.
+
+## Install
+
+Local development:
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e ".[dev]"
+fincli
+```
+
+Global npm wrapper:
+
+```bash
+npm install -g @drico2008/fincli
+fincli
+```
+
+The npm wrapper requires Python 3.11+ on the user machine. It creates an isolated `.npm-python` environment inside the installed package.
+
+## API Key Setup
+
+Global users do not need to edit `.env`. Save keys from inside FinCLI:
+
+```text
+/ai_model key groq <api_key>
+/ai_model key openrouter <api_key>
+/news_model key finnhub <api_key>
+/news_model key twelvedata <api_key>
+/news_model key alphavantage <api_key>
+```
+
+Keys are stored locally in:
+
+```text
+~/.fincli/secrets.env
+```
+
+FinCLI masks keys in terminal output. Use `/secrets status`, `/secrets clear`, `/privacy status`, and `/privacy purge` for local security hygiene.
+
+## Core Commands
+
+Research and market:
+
+```text
+/research AAPL
+/research AAPL --deep
+/research AAPL --report
+/research AAPL --report --export md report.md
+/research AAPL --report --export json report.json
+/market AAPL 1d
+/news AAPL 7d
+/technical AAPL 1d
+/analyze AAPL 1d
+/mtf AAPL 1d,1h,15m
+/calendar week US high
+```
+
+Providers:
+
+```text
+/news_model
+/news_model list
+/news_model priority google_news_rss,yfinance,yahoo_finance_rss
+/provider status
+/provider metrics
+/provider list
+/provider entitlement
+/provider key status
+/provider test AAPL
+```
+
+Portfolio and risk:
+
+```text
+/portfolio
+/portfolio add AAPL 10 185
+/portfolio performance
+/portfolio risk
+/tx add buy AAPL 10 185
+/tx add sell AAPL 5 195
+```
+
+Workflow:
+
+```text
+/watchlist add AAPL
+/scan watchlist rsi<30
+/journal add AAPL bullish "Breakout failed, wait for confirmation"
+/journal stats
+/journal review
+/alert add AAPL above 200
+/history
+/cache stats
+/cache clear
+```
+
+Security and release:
+
+```text
+/secrets status
+/privacy status
+npm run prepublish:safety
+python scripts/prepublish_check.py
+```
+
+## Research Engine v2
+
+`/research` is the central research command. It returns a compact output:
+
+- Snapshot
+- Signal
+- Risk
+- Missing Data
+- Source Quality
+- Decision Points
+- Final Summary
+
+Deep mode sends a concise Research Engine v2 prompt to the active AI provider. Report mode adds report-oriented notes without creating another command surface.
+
+## Portfolio Risk v3
+
+`/portfolio risk` calculates:
+
+- Exposure by asset class
+- Currency exposure
+- Concentration risk
+- Drawdown estimate
+- Asset-class cap warning
+- Risk budget from `/profile`
+- Realized PnL
+- Unrealized PnL
+- Total PnL
+- Portfolio health score
+
+The health score is a local analytical score, not financial advice. It penalizes high concentration, missing prices, weak diversification, and drawdown.
+
+## Data Notes
+
+- yfinance is a delayed fallback and should not be described as realtime.
+- Finnhub, Twelve Data, Alpha Vantage, and other providers may require API keys, paid plans, and exchange entitlements.
+- Public RSS/news sources can change or fail without notice.
+- Calendar fallback may be `schedule_only` if actual provider data is unavailable.
+- AI output is informational and must not be treated as guaranteed signal or financial advice.
+
+## Local Storage
+
+FinCLI stores local data under:
+
+```text
+~/.fincli/config.json
+~/.fincli/secrets.env
+~/.fincli/fincli.db
+~/.fincli/fincli.log
+```
+
+Do not commit `.env`, local secrets, logs, databases, cache folders, or npm/python virtual environments.
+
+## Prepublish Safety
+
+Before publishing to npm or GitHub:
+
+```bash
+python -m pytest -q
+python -m compileall fincli tests scripts
+npm run check
+npm run prepublish:safety
+```
+
+The prepublish checker scans for `.env`, `secrets.env`, logs, SQLite databases, token-like strings, and unsafe `npm pack --dry-run` contents.
+
+## Roadmap
+
+### v0.3.x Hardening
+
+- Provider runtime metrics by provider started in `/provider metrics`.
+- Persistent provider metrics started in v0.3.0.
+- AI Grounding Guard started in `/analyze`.
+- Richer portfolio analytics: drawdown estimate and currency grouping started in Portfolio Risk v3.
+- Better research reports with Markdown/JSON export from `/research --report` started in v0.3.0.
+- Provider-specific schema validation for custom data APIs.
+- Improved AI grounding and citations for web/news-assisted answers.
+
+### v0.4
+
+- Strategy builder.
+- Alert daemon and notification integrations.
+- Backtesting with fees, slippage, and position sizing.
+- Optional cloud sync.
+- Plugin marketplace-style connector loading.
+- Realtime streaming where provider plans support it.
+
+## License
+
+MIT

package/fincli/__init__.py

@@ -1,3 +1,3 @@
 """FinCLI package."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"

package/fincli/app/analysis/ai_prompts.py

@@ -5,41 +5,43 @@ You are FinCLI's market analysis assistant.
 
 Rules:
 - Analyze only from the provided OHLCV, indicators, market structure, and news/fundamental context.
-- Treat the provided Signal Assessment as a rule-based candidate signal, not a guaranteed trade instruction.
-- Treat the provided User Gameplay Profile as a risk constraint for SL/TP sizing and scenario wording.
+- Treat the provided Signal Assessment as a rule-based candidate signal, not a guaranteed trade instruction.
+- Treat the provided User Gameplay Profile as a risk constraint for SL/TP sizing and scenario wording.
 - Do not invent prices, news, fundamentals, or certainty.
-- If data is missing, state that data quality is insufficient.
+- If data is missing, state that data quality is insufficient.
 - Use the AI Grounding Guard before conclusions: check data_quality, provider reliability, missing data, and provider metrics.
+- Obey the Data Trust Gate exactly. If Trust Level is blocked or limited, Signal must be CAUTION/WAIT, SL/TP must be conditional or "not valid until data is verified".
 - If reliability is not ok, missing data exists, or provider metrics show weak success/error performance, reduce confidence and say what must be verified.
-- Use probabilistic scenario language, not guaranteed entry signals.
+- Use probabilistic scenario language, not guaranteed entry signals.
 - If discussing buy/sell, phrase it as candidate bias with confirmation and invalidation conditions.
 - Do not promise profit.
 - Keep the output structured and concise.
 - Add a short non-financial-advice disclaimer.
 
-Required output:
-Instrument:
-Timeframe:
-Data Quality:
-Provider Reliability:
-Missing Data:
+Required output:
+Instrument:
+Timeframe:
+Data Quality:
+Provider Reliability:
+Missing Data:
 Provider Metrics:
+Data Trust Gate:
 Market Summary:
-Trend Bias:
-Key Levels:
-Technical Indicators:
-Market Structure:
-Signal Assessment:
-Signal:
-SL:
-TP1:
-TP2:
-TP3:
-Reason:
-News/Fundamental Context:
-Bullish Scenario:
-Bearish Scenario:
-Risk Notes:
-Conclusion:
-Disclaimer:
+Trend Bias:
+Key Levels:
+Technical Indicators:
+Market Structure:
+Signal Assessment:
+Signal:
+SL:
+TP1:
+TP2:
+TP3:
+Reason:
+News/Fundamental Context:
+Bullish Scenario:
+Bearish Scenario:
+Risk Notes:
+Conclusion:
+Disclaimer:
 """

package/fincli/app/analysis/analyzer.py

@@ -4,11 +4,11 @@ from __future__ import annotations
 
 from fincli.app.analysis.ai_prompts import MARKET_ANALYSIS_PROMPT
 from fincli.app.analysis.indicators import TechnicalSummary
-from fincli.app.analysis.market_structure import MarketStructureSummary
-from fincli.app.analysis.technical_debate import format_debate, run_technical_debate
-from fincli.app.analysis.technical_signal import format_signal
-from fincli.app.analysis.trading_methods import analyze_trading_methods, format_trading_methods_context
-from fincli.app.providers.market.base import Candle
+from fincli.app.analysis.market_structure import MarketStructureSummary
+from fincli.app.analysis.technical_debate import format_debate, run_technical_debate
+from fincli.app.analysis.technical_signal import format_signal
+from fincli.app.analysis.trading_methods import analyze_trading_methods, format_trading_methods_context
+from fincli.app.providers.market.base import Candle
 
 
 def market_analysis_prompt() -> str:
@@ -16,17 +16,17 @@ def market_analysis_prompt() -> str:
     return MARKET_ANALYSIS_PROMPT.strip()
 
 
-def build_market_analysis_prompt(
-    symbol: str,
-    timeframe: str,
-    candles: list[Candle],
-    technical: TechnicalSummary,
-    structure: MarketStructureSummary | None = None,
-    news_context: str = "No news/fundamental context provided.",
-    user_gameplay_context: str = "User Gameplay Profile: not configured.",
-    trading_methods_context: str = "",
-    grounding_context: str = "",
-) -> str:
+def build_market_analysis_prompt(
+    symbol: str,
+    timeframe: str,
+    candles: list[Candle],
+    technical: TechnicalSummary,
+    structure: MarketStructureSummary | None = None,
+    news_context: str = "No news/fundamental context provided.",
+    user_gameplay_context: str = "User Gameplay Profile: not configured.",
+    trading_methods_context: str = "",
+    grounding_context: str = "",
+) -> str:
     """Build a structured AI prompt from market data and computed indicators."""
     recent = candles[-10:]
     ohlcv_lines = [
@@ -55,29 +55,29 @@ def build_market_analysis_prompt(
     debate = run_technical_debate(technical, structure, candles) if structure is not None else None
     return (
         f"{market_analysis_prompt()}\n\n"
-        f"Instrument: {symbol}\n"
-        f"Timeframe: {timeframe}\n"
-        f"Data Quality: {len(candles)} candles available from provider.\n\n"
-        "AI Grounding Guard:\n"
-        f"{grounding_context or 'Data Quality: unknown; Provider Reliability: unknown; Missing Data: unknown; Provider Metrics: unavailable.'}\n"
-        "Instruction: If reliability is not ok, missing data exists, or provider metrics are weak, reduce confidence before conclusion.\n\n"
-        "Recent OHLCV:\n"
+        f"Instrument: {symbol}\n"
+        f"Timeframe: {timeframe}\n"
+        f"Data Quality: {len(candles)} candles available from provider.\n\n"
+        "AI Grounding Guard:\n"
+        f"{grounding_context or 'Data Quality: unknown; Provider Reliability: unknown; Missing Data: unknown; Provider Metrics: unavailable.'}\n"
+        "Instruction: If reliability is not ok, missing data exists, or provider metrics are weak, reduce confidence before conclusion.\n\n"
+        "Recent OHLCV:\n"
         f"{chr(10).join(ohlcv_lines)}\n\n"
         "Computed Indicators:\n"
         f"{chr(10).join(indicator_lines)}\n\n"
         "Market Structure:\n"
         f"{_format_structure(structure)}\n\n"
-        "Signal Assessment:\n"
-        f"{format_signal(debate.judge_signal) if debate is not None else 'No signal assessment available.'}\n\n"
-        "Technical Debate:\n"
-        f"{format_debate(debate) if debate is not None else 'No technical debate available.'}\n\n"
-        "Trading Method Context:\n"
-        f"{trading_methods_context or format_trading_methods_context(analyze_trading_methods(candles))}\n\n"
-        "User Gameplay Context:\n"
-        f"{user_gameplay_context}\n\n"
-        "News/Fundamental Context:\n"
-        f"{news_context}\n"
-    )
+        "Signal Assessment:\n"
+        f"{format_signal(debate.judge_signal) if debate is not None else 'No signal assessment available.'}\n\n"
+        "Technical Debate:\n"
+        f"{format_debate(debate) if debate is not None else 'No technical debate available.'}\n\n"
+        "Trading Method Context:\n"
+        f"{trading_methods_context or format_trading_methods_context(analyze_trading_methods(candles))}\n\n"
+        "User Gameplay Context:\n"
+        f"{user_gameplay_context}\n\n"
+        "News/Fundamental Context:\n"
+        f"{news_context}\n"
+    )
 
 
 def build_technical_ai_summary(symbol: str, timeframe: str, candles: list[Candle]) -> str:

package/fincli/app/analysis/assistant_context.py

@@ -6,11 +6,11 @@ import re
 
 
 FINCLI_ASSISTANT_SYSTEM_PROMPT = """
-You are FinCLI AI Assistance, the embedded assistant inside FinCLI v0.3.1.
+You are FinCLI AI Assistance, the embedded assistant inside FinCLI v0.4.0.
 
 Identity and scope:
-- FinCLI is a terminal-first financial dashboard for market data, news/fundamentals, technical analysis, watchlists, portfolios, journals, and provider configuration.
-- FinCLI commands start with slash commands inside the TUI, for example /help, /research AAPL --quick, /macro US, /profile, /technical AAPL, and /analyze XAUUSD.
+- FinCLI is a terminal-first financial dashboard for market data, news/fundamentals, technical analysis, watchlists, portfolios, journals, and provider configuration.
+- FinCLI commands start with slash commands inside the TUI, for example /help, /research AAPL --quick, /macro US, /profile, /technical AAPL, and /analyze XAUUSD.
 - Your role is to help users understand markets, risk, portfolio context, trading journal patterns, FinCLI commands, and general non-coding questions.
 - Free chat is allowed, but you must keep your identity as FinCLI's assistant and be clear when market data is unavailable or delayed.