vn-finance-mentor

Vietnam and US market data, research signals, and paper monitoring.
Fundamentals • Technicals • Macro • News • Screening • Fund Analysis

Overview

vn-finance-mentor is a Python library for Vietnam/US market data, deterministic research signals, backtesting, and self-hosted paper monitoring. The AI plugin provides Vietnamese market analysis for Codex, Claude Code, Cursor, and GitHub Copilot, with repository marketplaces for Codex and Claude Code.

Version 0.2.0 adds the self-hosted VN/US market monitor runtime alongside the existing data and strategy APIs.

Ask natural language questions — the plugin auto-routes to the right analysis workflow:

"Analyze FPT stock"
"Market overview today"
"Compare VNM vs MSN"
"Latest news sentiment for HPG"

Example: Stock Analysis in Action

Claude Code analyzing HPG stock — orchestrating fundamental and technical agents in parallel. Download plugin →

Features

• Codex Marketplace — install the bundled plugin from this repository or generate a plugin and marketplace in another project
• Stock Analysis — valuation, financial health, technical indicators, screening, sentiment, sector analysis
• Market Research — market valuation (P/E, P/B), sector comparison, fund analysis, commodities
• Technical Analysis — 30+ indicators: SMA, EMA, RSI, MACD, Bollinger Bands, ATR, OBV, and more
• Macro Research — GDP, CPI, interest rates, exchange rates, FDI, trade balance
• News & Sentiment — crawl and classify news from Vietnamese financial sites (CafeF, VnExpress, etc.)
• Fund Analysis — 58+ mutual funds: NAV, holdings, industry allocation, performance
• Bond Analysis — corporate and government bond discovery plus OHLCV, trades, and quotes
• Batch Collection — scheduled OHLCV, financial, and intraday data collection tasks
• Official Market Feeds — DNSE, SSI FastConnect, Alpaca IEX, and SEC EDGAR
• Capability Routing — opt-in source="AUTO" with source, attempted_sources, market, fetched_at, data_timestamp, delayed_seconds, and coverage provenance
• Signal Validation — long-only regime strategies, next-bar backtests, and strict walk-forward holdout gates that downgrade to NO_TRADE
• Paper Monitor — unusual-flow detection, restart-safe SQLite paper/equity state, Telegram alerts, daily HTML summaries, and Docker deployment; paper-trade only, no broker connections

Installation

The Python distribution is vn-finance-mentor, the npm installer is vn-finance-mentor-cli, and its executable is vn-finance-mentor. Python code continues to import claude_finance_kit; monitor commands use cfk.

Use Python 3.12 for the verified setup. The package currently declares Python 3.10+, but Python 3.10 has a known import failure involving datetime.UTC.

1. Install the Python library from source

From the repository root:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

For realtime monitoring, install the extra in the same environment:

python -m pip install -e ".[monitor]"

pip install vn-finance-mentor

pip install "vn-finance-mentor[monitor]"
cfk monitor init
cfk monitor doctor
cfk monitor run

monitor doctor performs live data, stream-auth/entitlement, and Telegram authentication probes by default. Use --offline only for a local configuration check.

2. Install the AI plugin

codex plugin marketplace add .
codex plugin marketplace list

cd cli
npm ci
npm run build
cd ..

node /absolute/path/to/vn-finance-mentor/cli/dist/index.js init --ai codex-plugin
codex plugin marketplace add .

node /absolute/path/to/vn-finance-mentor/cli/dist/index.js init --ai codex

/plugin marketplace add hongbietcode/vn-finance-mentor

/plugin install vn-finance-mentor@vn-finance-mentor

npx vn-finance-mentor-cli init --ai cursor    # Cursor
npx vn-finance-mentor-cli init --ai copilot   # GitHub Copilot
npx vn-finance-mentor-cli init --ai claude    # Claude Code (CLI alternative)

Quick Start

Once installed, just ask naturally — the plugin auto-invokes the right skill:

"Analyze FPT stock"                                        → vn-finance-mentor (stock deep dive)
"Market overview today"                                    → vn-finance-mentor (market briefing)
"Compare VNM vs MSN"                                       → vn-finance-mentor (comparative)
"Latest news sentiment for HPG"                            → vn-finance-mentor (news sentiment)

To invoke the skill explicitly, use $vn-finance-mentor in Codex or /vn-finance-mentor in Claude Code, followed by your question.

Python Library Usage

from claude_finance_kit import Bond, Stock, Market, Macro, Commodity, Fund

# Stock data
stock = Stock("FPT")
stock.quote.history(start="2025-01-01", end="2025-12-31")
stock.finance.income_statement(period="quarter")
stock.company.overview()

# Bond data
bond = Bond("BAB123032")
bond.ohlcv(start="2025-01-01")
bond.trades()
bond.quote()

# Market valuation
market = Market("VNINDEX")
market.pe(duration="5Y")
market.top_gainer(limit=10)

# Macro indicators
macro = Macro()
macro.gdp()
macro.cpi()
macro.interest_rate()

# Commodities
commodity = Commodity()
commodity.gold()
commodity.oil()

# Fund analysis
fund = Fund()
fund.listing("STOCK")

VN/US routing and trading data

from claude_finance_kit import Stock

vn = Stock("FPT", market="VN", source="AUTO")
us = Stock("AAPL", market="US", source="AUTO")

bars = us.quote.history(start="2025-01-01")
trades = vn.trading.trades(limit=500)
quotes = us.trading.order_book(limit=100)

Explicit sources remain strict and backward compatible. AUTO results record source, attempted_sources, market, fetched_at, data_timestamp, delayed_seconds, and coverage in DataFrame.attrs.

Realtime monitor

The self-hosted monitor ships in 0.2.0 and is configured with cfk monitor. cfk monitor init creates both monitor.toml and a local .env.example. Populate the secrets for the providers you intend to use before running cfk monitor doctor and cfk monitor run:

SSI_CONSUMER_ID
SSI_CONSUMER_SECRET
DNSE_API_KEY
DNSE_API_SECRET
ALPACA_API_KEY
ALPACA_API_SECRET
FMP_API_KEY
CFK_SEC_USER_AGENT
CFK_TELEGRAM_BOT_TOKEN
CFK_TELEGRAM_CHAT_ID

An explicit VN watchlist can fall back to AUTO intraday polling when SSI/DNSE stream credentials are unavailable. The runtime labels that mode degraded, blocks BUY and never treats it as all-market scanning. SSI credentials and ALL entitlement remain mandatory for a full-market VN stream. US can use degraded FMP polling when Alpaca is unavailable, but still requires FMP_API_KEY.

Passing validation is tied to the exact market, regime, benchmark, strategy name, parameter set, source-data fingerprint, and freshness window. Feed timestamps that are stale, out of order, duplicated, or too far in the future block BUY. Outside the configured weekday exchange hours the feed is idle; incoming extended-hours records are quarantined, and holiday calendars are not inferred. SQLite commits signal dedupe, paper state, and the Telegram outbox atomically so a notification failure does not lose the signal or stop the monitor. Completed minute aggregates are restored after a restart; routine HOLD states are not sent as recurring alerts.

The monitor writes a daily HTML report to reports/monitor-YYYY-MM-DD-report.html. The cfk backtest command writes a backtest HTML report to reports/{symbol}-{strategy}-backtest-report.html.

Technical Analysis

from claude_finance_kit import Stock
from claude_finance_kit.ta import Indicator

stock = Stock("FPT")
df = stock.quote.history(start="2025-01-01", end="2025-12-31")
df = df.set_index("time")

ind = Indicator(df)
ind.trend.sma(length=20)
ind.trend.ema(length=50)
ind.momentum.rsi(length=14)
ind.momentum.macd(fast=12, slow=26, signal=9)
ind.volatility.atr(length=14)
ind.volume.obv()

Data Sources

Source fallback: Explicit providers never silently change source. Use Stock("FPT", market="VN", source="AUTO") for capability-aware fallback. Authentication, invalid-symbol, and malformed-data errors do not trigger fallback.

Plugin Architecture

• Python library — data APIs, strategies, and monitor runtime.
• CLI installer — platform installation and removal commands.
• Codex marketplace and Claude Code marketplace — repository plugin catalogs.
• Codex manifest and Claude Code manifest — metadata for the bundled plugin.
• Platform templates — standalone skills and Codex plugin scaffolding.
• VN Finance Mentor skill — analysis workflows, references, and scripts.

Skills & Agents

Environment Variables

Documentation

Development

cd cli
npm install
npm run build              # Build CLI TypeScript
npm run bump -- patch      # Bump version (patch|minor|major)

Version Sync

npm run bump synchronizes the Python, npm, and plugin versions. The Codex marketplace reads the bundled plugin's manifest version.

Publishing

The release workflow creates a release when a pull request merges into main, publishes Python/npm packages, and attaches the plugin ZIP. The publish workflow also handles published GitHub releases. Pushing a tag alone does not trigger either workflow.

To publish only the Python package at the version in pyproject.toml, run:

gh workflow run publish.yml --repo hongbietcode/vn-finance-mentor --ref main

PyPI Trusted Publishing must authorize repository hongbietcode/vn-finance-mentor, workflow publish.yml, and environment release. Configure a pending publisher in PyPI account publishing settings before the first release under a new package name. The merge-triggered release workflow uses release.yml and needs its own trusted publisher.

To build the plugin archive locally, run npm run package inside cli/ after building the installer. The output is cli/vn-finance-mentor-<version>.zip and includes both plugin manifests. The repository marketplace catalog is distributed with the repository itself.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -m 'feat: add my feature')
4. Push to the branch (git push origin feat/my-feature)
5. Open a Pull Request

License

MIT

Disclaimer

Reports generated by this toolkit are for reference only and do not constitute investment advice. You are responsible for your own capital allocation and risk management.