Gọi bằng JSON và MCP

Các hàm danh mục, định giá và backtest của vnstock_quant gọi được bằng tên hàm cộng một đối tượng JSON tham số, và trả về JSON. Mỗi hàm có JSON Schema mô tả tham số, nên dùng trực tiếp làm định nghĩa công cụ cho trợ lý AI (MCP, function calling) mà không cần viết lớp chuyển đổi. Lời gọi JSON đi qua cùng lõi Rust và cùng bước kiểm tra quyền như hàm Python, nên một máy chủ MCP chạy trên máy bạn vẫn theo đúng cấp của bạn.

Catalog và schema

from vnstock_quant import portfolio as pm

cat = pm.catalog()                    # name, group, describe, standard
cat.groupby("group").size()           # construct, fees, holdings, returns, risk, valuation

pm.schema("twr")
# {'name': 'twr', 'group': 'returns', 'describe': '...', 'standard': 'CFA L1 QM LM1 p.32–33, Eq.6',
#  'parameters': {'type': 'object', 'properties': {...}, 'required': ['dates', 'values']}}

Mỗi tham số trong parameters.properties có type, description và default nếu có. Trường standard ghi chuẩn hoặc tài liệu gốc của phép tính.

Định nghĩa công cụ cho mọi hàm danh mục và định giá:

tools = [
    {"name": s["name"], "description": s["describe"], "input_schema": s["parameters"]}
    for s in (pm.schema(n) for n in pm.catalog()["name"])
]
len(tools)      # 38

Mô-đun backtest có 15 công cụ cùng dạng, schema ghi theo cách MCP đặt tên (name, description, input_schema):

from vnstock_quant import backtest as bt

list(bt.catalog()["name"])
# ['list_brokers', 'list_profiles', 'list_presets', 'list_indicators', 'eval_rule_dsl',
#  'check_rule_dsl_causality', 'detect_limit_events', 'run_backtest', 'run_portfolio', 'sweep',
#  'walk_forward', 'monte_carlo', 'deflated_sharpe_ratio', 'run_fixture_demo', 'portfolio_analytics']
bt.schema("run_backtest")["input_schema"]["required"]      # ['bars']

Năm công cụ mới ở bản 1.0 đưa phần danh mục và chống quá khớp ra lời gọi JSON, cùng tham số với hàm Python tương ứng:

Kết quả của run_backtest có thêm daily_returns, để đưa thẳng vào monte_carlo hay deflated_sharpe_ratio mà không phải tính lại.

Gọi hàm

pm.call("annualize", r=0.20, days=548)
# {'value': 0.1290..., 'exponent': 0.666...}

pm.call("ddm", r=0.15, d0=5000, stages=[[0.10, 3]], terminal_g=0.05)

pm.call(
    "twr",
    dates=[19724, 19877, 20090],        # số ngày kể từ 1970-01-01
    values=[100e6, 112e6, 150e6],
    flows=[0, 30e6, 0],
)

Với backtest, nến đi vào dưới dạng danh sách đối tượng (date theo YYYY-MM-DD, open, high, low, close, volume) và bảng quy tắc là đối tượng JSON, đúng dạng trợ lý AI tạo ra từ một câu mô tả:

bars = [
    {"date": "2024-01-02", "open": 50.0, "high": 50.5, "low": 49.5, "close": 50.2, "volume": 100000},
    # ... các phiên tiếp theo, thứ tự thời gian tăng dần
]
res = bt.call(
    "run_backtest",
    bars=bars,
    dsl={"entry_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "cross_above", "right": 30}],
         "exit_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "gt", "right": 70}]},
    stop_loss_pct=0.07,
)
res.keys()                                  # tear_sheet, trades, rejected_orders, open_positions, warnings, daily_returns
res["tear_sheet"]["total_return_pct"], res["tear_sheet"]["sharpe_ratio"]

Quy ước của lời gọi JSON:

• Ngày là số ngày kể từ 01/01/1970 với các hàm danh mục, chuỗi YYYY-MM-DD với các công cụ backtest.
• Mảng là danh sách số; ma trận là danh sách các hàng.
• Tỷ lệ là phân số: 0.18 nghĩa là 18%.
• Tham số lạ bị từ chối, để trợ lý AI biết mình gọi sai.
• Lỗi trả về có mã ổn định (QUANT_INVALID_PARAMETER, QUANT_INPUT_DATA, QUANT_UNKNOWN_FUNCTION, QUANT_UNKNOWN_TOOL) và thông điệp nói rõ tham số nào sai, nhờ đó trợ lý AI tự sửa được lời gọi.

from vnstock_quant.errors import InvalidParameterError

try:
    pm.call("twr", dates=[0, 1], values=[1, 2], bogus=1)
except InvalidParameterError as e:
    print(e.code, e)        # QUANT_INVALID_PARAMETER [QUANT_INVALID_PARAMETER] `twr` không có tham số `bogus`

Catalog đọc được bằng máy của các nhóm còn lại

ta, fa, risk và micro dùng hàm Python thường, nhưng catalog của chúng cũng là bảng có cấu trúc để trợ lý AI tra tên, đơn vị và chuẩn đối chiếu trước khi viết mã:

from vnstock_quant import fa, risk, ta

ta.catalog()[["name", "group", "standard", "confidence"]].head()
risk.catalog().to_dict("records")[:2]     # name, benchmark, unit, describe, standard
fa.catalog()[["id", "describe", "unit", "access"]].head()
fa.describe("RT_PRT_ROE")                  # công thức theo mẫu ngành và hồ sơ

Vnstock MCP

Vnstock MCP là máy chủ MCP chạy trên máy bạn, đưa các hàm của vnstock_quant tới trợ lý AI dưới dạng công cụ. vnstock-mcp 1.0.0rc1 đi cùng vnstock_quant 1.0.0rc1 và vnstock 6: có quant_ta, quant_fa, quant_risk, quant_returns, quant_portfolio, quant_prices, quant_micro, quant_backtest (gồm cả danh mục, dò tham số, walk-forward, Monte Carlo, Sharpe đã hiệu chỉnh) và quant_catalog để tra tham số. Dữ liệu đi vào công cụ là bảng đã tải trong phiên làm việc của MCP, nên trợ lý không phải chép số qua lời nhắc. Quyền, lượt thử và cảnh báo giống như khi bạn gọi hàm Python; cảnh báo của thư viện nằm trong trường warnings của kết quả.

Danh mục công cụ: Danh mục công cụ Vnstock MCP v1.

Quyền

portfolio và valuation cần cấp Bronze; backtest một mã với 10 chỉ báo cơ bản mở cho mọi cấp theo lượt thử, các công cụ còn lại của backtest từ Bronze. Lời gọi JSON qua cùng cổng quyền, cùng lượt thử và cùng quy mô mỗi lần chạy với hàm Python, nên không vượt được giới hạn của cấp bằng cách gọi qua JSON. Bảng đầy đủ: Quyền dùng và hạn mức.

Đọc tiếp

• Danh mục — Ý nghĩa và cách dùng của 38 hàm trong catalog.
• Dữ liệu và tín hiệu trong backtest — Cấu trúc bảng quy tắc rule_dsl.
• Hướng dẫn cho trợ lý AI — Thiết lập môi trường làm việc với trợ lý AI.