VNStock Free Expert

Use this skill when the user needs advanced Vietnam stock analysis with vnstock, while staying safe on free-tier limits.

Important packaging note

• references/

Read order

• Read references/capabilities.md.
• Read references/method_matrix.md for exact class/method mapping.
• Read references/free_tier_playbook.md before large runs.

Scope and constraints

• Library: vnstock only.
• Preferred sources: kbs first, vci fallback.
• Never use tcbs.
• Treat Screener API as unavailable unless user confirms it is restored in their installed version.

Free-tier operating rules

• No API key: target <= 20 requests/minute.
• Free API key: target <= 60 requests/minute.
• Safe default pacing in scripts: 3.2s/request.
• Reuse cached artifacts between steps.

Shared confidence rubric (required)

• High: universe coverage >= 95%, critical metrics coverage >= 80%, and hard errors <= 5% of symbols.
• Medium: universe coverage >= 80%, critical metrics coverage >= 60%, and hard errors <= 15%.
• Low: below Medium thresholds or material missing fields that can flip ranking results.

• Confidence level.
• Coverage stats (symbols_requested, symbols_scored, % missing by key metric).
• Top missing fields that may change conclusions.

API key configuration (implemented)

• Skill-local key file: .env
• Variable: VNSTOCK_API_KEY
• All API-calling scripts auto-load this key and call vnstock auth setup before requests.
• You can override per run with --api-key "...".

Execution workflow (ordered)

• Validate environment (python, vnstock, pandas) and load optional API key from .env.
• Build a universe using scripts/build_universe.py (group, exchange, or symbols mode).
• Collect market data with scripts/collect_market_data.py using safe pacing.
• Collect fundamentals with scripts/collect_fundamentals.py.
• Score and rank using scripts/score_stocks.py.
• Generate analyst-style memo with scripts/generate_report.py.
• Apply confidence rubric, disclose missing fields, and summarize risks.

Downstream handoff bundle (required when doing single-ticker deep dive)

• ticker, as_of_date, currency
• financials (income/balance/cashflow + key ratios if available)
• price_history (returns 1m/3m/6m/12m)
• peer_set (if you built one)
• metadata.source and data_quality_notes

Script map

A) Discovery and universal invocation (for broad feature coverage)

• catalog_vnstock.py

Use when:

• You need to inspect available classes/methods in the installed vnstock version.
• You want to confirm compatibility before running a method.
• invoke_vnstock.py

Use when:

• You need to call any supported class/method beyond the prebuilt valuation pipeline.
• You want one generic entry point for Listing, Quote, Company, Finance, Trading, Fund, or other exported classes.

B) Valuation pipeline scripts

• build_universe.py

• collect_market_data.py

• collect_fundamentals.py

• score_stocks.py

• generate_report.py

• run_pipeline.py

Error handling rules

• Log symbol-level failures and continue processing remaining symbols.
• Do not claim missing metrics as zeros; mark them as missing.
• If a critical step fails, stop and report failed step + command + suggested retry scope.

Recommended decision logic

• If request is “standard valuation/ranking”: run pipeline scripts.
• If request needs a specific vnstock capability not in pipeline: use catalog_vnstock.py then invoke_vnstock.py.
• If request volume is large: apply free_tier_playbook.md throttling and chunking strategy.

Confidence aggregation (required)

• Compute data confidence from coverage metrics (symbols_scored, missing key fields, error ratio).
• Compute model confidence from method robustness (single metric vs multi-factor consistency).
• Final confidence = lower of data confidence and model confidence.
• In Low confidence cases, provide directional output only and list required missing inputs.

Required output template

• What Was Run: scripts, source, universe scope, and pacing profile.
• Coverage: requested symbols, scored symbols, and missingness by key field.
• Top Results: ranked list with score columns.
• Key Risks: concentration, stale data, missing metrics, or provider limitations.
• Confidence and Gaps: final confidence + exact blockers.

Quick command examples

python scripts/catalog_vnstock.py --outdir ./outputs
python scripts/invoke_vnstock.py --class-name Quote --init-kwargs '{"source":"kbs","symbol":"VCB"}' --method history --method-kwargs '{"start":"2024-01-01","end":"2024-12-31","interval":"1D"}' --outdir ./outputs
python scripts/run_pipeline.py --source kbs --mode group --group VN30 --outdir ./outputs

Trigger examples

• "Analyze VN30 using vnstock but keep it free-tier safe."
• "Rank Vietnamese stocks by value/quality/momentum with KBS data."
• "Run a full vnstock pipeline and return top candidates with risk notes."