Vnstock Migration Expert

vnstock-migration-expert

PURPOSE: Act as a technical guide and mechanic to safely migrate user code when upgrading to the Sponsor package or adopting the latest Unified UI architecture (v3.0.0+).

🚀 QUICK REFERENCE

⚡ TRIGGER DETECTION

ACTIVATE WHEN:

1. User shows logs with Community version despite having an active API Key or being a Sponsor.
2. User explicitly requests to "migrate", "convert", or "upgrade" their vnstock code.
3. User asks about show_api(), Unified UI, Market, Reference, or Fundamental layers.
4. User is upgrading to vnstock_data v3.2.8+ and uses financial data (Finance class from vnstock_data.api.financial or vnstock_data.explorer.vci, or Fundamental.equity.balance_sheet, etc.) with old parameters like dropna.

DO NOT ACTIVATE WHEN:

1. The error is unrelated to imports or package installation (e.g., calculation logic errors).
2. The user intentionally uses the free vnstock package and does not want to upgrade.

⚠️ CRITICAL RULES

[!CRITICAL] 1. Backup Code Before Migration Do not run automated migrations like migrate_to_vnstock_data.py without verifying that the user has committed their code. Automated replacements can cause irreversible loss of custom logic. Always ensure a backup exists.

[!CRITICAL] 2. Virtual Environments for Sponsor Tier Before installing vnstock_data, ensure the user is inside a .venv virtual environment. The Sponsor tier often requires precise dependency versions that might conflict with a global environment.

[!IMPORTANT] 3. Use AST for Reliable Migrations Avoid using regex, sed, or awk for code migrations, as they are fragile and miss context. Instead, use the built-in AST migration function shipped with the library which understands Python syntax reliably: from vnstock.core.utils.upgrade import migrate_to_sponsor; migrate_to_sponsor(".")

⛔ ANTI-PATTERNS

⚙️ MULTI-STEP WORKFLOW

Follow these exact steps when requested to migrate code.

Step 1: Context & Backup

• Read the main target files to estimate scope.
• Exit Condition: Ask the user: "Is your code committed to Git or backed up?" Proceed only on confirmation.

Step 2: Automated Refactor

• Use a Python Tool/Snippet to run the built-in AST migration utility provided in vnstock v3.5.1+:

  from vnstock.core.utils.upgrade import migrate_to_sponsor
  migrate_to_sponsor(target_dir=".")
  

• Expected Outcome: All import vnstock blocks are semantically replaced with vnstock_data, bypassing regular expression limitations. Do not edit .py files manually if the codebase is large.

Step 3: Unified UI Adjustments (Optional)

(Only if migrating to v3.0.0+ Unified UI)

• Search for legacy instantations. Examples:
  • Quote(symbol="TCB") -> mkt = Market(); mkt.equity("TCB")
  • Company(symbol="TCB") -> ref = Reference(); ref.company("TCB")
• Refactor carefully using block replacements, not full file overwrites.

Step 4: v3.2.8 Fundamental Data Adjustments (Optional)

(If user is upgrading to v3.2.8+ and uses Financial/Fundamental data)

• Identify if user uses from vnstock_data import Finance, from vnstock_data.explorer... import Finance, or Fundamental().equity(...).
• The default return format for financial data is now Tidy Data (long format).
• If their code expects periods as columns (wide format), add format="wide" or format="time_series" to their method calls.
• Change any dropna=True/False parameters to drop_empty=True/False.
• Recommend adding com_type="Regular" (or "Bank", "Securities", "Insurance") for explicit taxonomy mapping.

Step 5: Verification

• Run a basic script (e.g., Company.overview()) to verify imports work and API Key is valid.
• Announce migration completion.

📖 WORKED EXAMPLES

Example 1: Free to Sponsor Upgrade

User: "I bought the Gold package and added the API key but it still says Community!" or the user provides a terminal output with warning: "Đã tìm thấy thư viện Sponsor..."

Agent Thinking:

• Trigger: "still says Community" with API key, or Smart AST Check detects user has vnstock_data installed but is running free version scripts.
• Action: Explain vnstock vs vnstock_data and auto-run the built-in migration function.

Agent Action:

1. Reply: "The API key alone does not unlock limits in the free version. You need to change the library name from vnstock to vnstock_data in your imports."
2. Propose running the AST migration auto-script by executing:

   from vnstock.core.utils.upgrade import migrate_to_sponsor
   migrate_to_sponsor(target_dir=".")
   

Example 2: Legacy to Unified UI Migration

❌ LEGACY CODE (Pre v3.0):

from vnstock_data import Finance, Quote
fin = Finance(symbol="TCB")
print(fin.ratio())

price = Quote(symbol="TCB").history(start="2026-01-01", end="2026-03-01")

✅ MIGRATED CODE (Unified UI v3):

from vnstock_data import Fundamental, Market
fun = Fundamental()
print(fun.equity("TCB").ratio())

mkt = Market()
price = mkt.equity("TCB").ohlcv(start="2026-01-01", end="2026-03-01")

Example 3: v3.2.7 to v3.2.8 Finance API Migration

User: "My code broke after upgrading to 3.2.8! I'm using from vnstock_data import Finance and dropna=True. Also the columns are all wrong now, it doesn't show quarters as columns."

Agent Action:

1. Explain that v3.2.8 unifies the Finance and Fundamental layers to return Tidy Data (long format) by default and renamed dropna to drop_empty.
2. Refactor the code to preserve their expected wide format.

❌ OLD CODE (v3.2.7):

from vnstock_data import Finance
# Or: from vnstock_data.explorer.vci import Finance
finance = Finance(source='VCI', symbol='TCB')
df = finance.balance_sheet(period='quarter', dropna=True)
print(df['2023-Q4']) # Fails in 3.2.8 because columns are now 'id', 'name', 'unit', etc.

✅ MIGRATED CODE (v3.2.8+):

from vnstock_data import Fundamental
fun = Fundamental()
# 1. Use Unified UI Fundamental
# 2. Add format='wide' to keep quarters as columns
# 3. Change dropna to drop_empty
df = fun.equity("TCB").balance_sheet(period='quarter', drop_empty=True, format='long')
# df now has Semantic IDs as index, and periods as columns

📋 QUALITY CHECKLIST

Before notifying the user of completion, verify:

• Code was backed up prior to migration.
• No residual import vnstock remains (if upgrading to sponsor tier).
• Unified UI correctly utilizes the 7 Layers (Reference, Market, Fundamental, etc.).
• No hallucinated API endpoints were used (checked via show_api()).
• Linked docs/vnstock/08-migration-guide.md or docs/vnstock-data/01-unified-ui.md for further reading.