Skip to content

"Vibe-Trading: Your Personal Trading Agent"

21.9 KB
Raw Blame
"""T6 gate — ``paper_trade_step`` tool entry + MCP wrapper (Step 6).

Covers the registration seam end to end, offline: the orders-mode success
document, the in-band ``PAPER_DATA_NOT_READY`` envelope, ``INVALID_REQUEST``
for every malformed-input class (shape parse, the tool-owned orders XOR
strategy_path gate, a reversed range, the AM-3 single-day rule), the AM-4-1
rule that ``received_state_hash`` covers the RAW account_state (an added key
breaks it, an int/float respelling does not), the single degraded error-envelope
case (a malformed ``market`` echoed verbatim, T5 decision 5), the strategy_path
routing into the lazily-imported T7 ``strategy_exec.run_strategy_path`` (fake,
including the ``strategy_universe`` prefetch seam and its orders-mode absence),
the strategy_path end-to-end universe regression (a cash-only account + the
golden fixture's declared ``UNIVERSE`` must prefetch and fill), and the
hand-written MCP wrapper (payload build + delegation + description).

The research-only red line is asserted statically: the tool module carries no
scoped ``trading_*`` connector surface and no order-placement call.

Offline by construction: fake loader / fake CH client / fake calendar client,
no network (``--disable-socket`` hard gate), no clock (every date injected).
"""

from __future__ import annotations

import json
import re
import sys
import types
from pathlib import Path

import pandas as pd
import pytest

from src.config.paths import get_runtime_root
from src.tools.paper_trade import engine, state_hash
from src.tools.paper_trade import tool as tool_module
from src.tools.paper_trade.schema import (
    MARKETS,
    load_contract_schema,
    validate_payload,
)
from src.tools.paper_trade.tool import PaperTradeStepTool, run_paper_trade_step

_CN_A_DAY = "2026-10-20"  # Tuesday
_CN_A_PREV = "2026-10-19"
_HK_DAY = "2026-10-16"  # Friday
_SHA_RE = re.compile(r"^[0-9a-f]{64}$")

# The T7 synthetic fixture day (index 39: close 128.5, sma5 127.5, sma20
# 123.75 — the golden SMA cross) and the §4 us default fee matrix (AM-4-3).
_US_DAY = "2026-03-02"
_US_FEES = {"commission_per_share": 0.0049, "commission_min": 0.99, "sec_fee_rate": 0.0}
_FIXTURES = Path(__file__).parent / "fixtures" / "paper_trade"
_SYNTH_FIXTURE = _FIXTURES / "market" / "synthetic_split_4to1.json"
_GOLDEN_STRATEGY = _FIXTURES / "strategies" / "golden_sample_sma.py"

_CN_A_FEES = {
    "commission_rate": 0.00025,
    "commission_min": 5.0,
    "stamp_tax_sell": 0.0005,
    "transfer_fee": 0.00001,
}
_HK_FEES = {
    "commission_rate": 0.0003,
    "commission_min": 3.0,
    "stamp_tax_rate": 0.001,
    "regulatory_levy_rate": 0.00003,
}


class FakeChClient:
    def __init__(self, frames: dict[str, pd.DataFrame]) -> None:
        self._frames = frames

    def get_bars(self, ts_code: str, start_date: str, end_date: str) -> pd.DataFrame:
        return self._frames.get(ts_code, pd.DataFrame())


class FakeLoader:
    def __init__(self, frames: dict[str, pd.DataFrame], name: str = "tencent") -> None:
        self.name = name
        self._frames = frames

    def is_available(self) -> bool:
        return True

    def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None):
        return {c: self._frames[c] for c in codes if c in self._frames}


class FakeCalendarClient:
    """cn_a CH trade_calendar truth: exactly the given days are open."""

    def __init__(self, open_days: tuple[str, ...]) -> None:
        self._open = set(open_days)

    def get_trade_calendar(self, start_date: str, end_date: str) -> pd.DataFrame:
        rows = [
            {"exchange": "SSE", "cal_date": day.strftime("%Y-%m-%d"),
             "is_open": int(day.strftime("%Y-%m-%d") in self._open), "pretrade_date": ""}
            for day in pd.date_range(start_date, end_date)
        ]
        return pd.DataFrame(rows, columns=["exchange", "cal_date", "is_open", "pretrade_date"])


def _frame(rows: list[tuple[str, float]]) -> pd.DataFrame:
    records = [
        {"trade_date": day, "open": close, "high": close, "low": close, "close": close,
         "volume": 1000.0}
        for day, close in rows
    ]
    frame = pd.DataFrame(records)
    frame["trade_date"] = pd.to_datetime(frame["trade_date"])
    return frame.set_index("trade_date")


def _payload(**overrides) -> dict:
    base = {
        "account_id": "pa_t6",
        "market": "cn_a",
        "account_state": {"cash": 200000.0, "positions": []},
        "orders": [{"symbol": "600519.SH", "side": "buy", "qty": 100}],
        "from_date": _CN_A_DAY,
        "to_date": _CN_A_DAY,
        "fee_model": dict(_CN_A_FEES),
    }
    base.update(overrides)
    return base


def _cn_a_fakes(*, target_bar: float | None = 1421.0, prev_bar: float | None = 1418.0):
    """Fake loader/ch/calendar for a cn_a run; ``None`` omits that leg's bar."""
    loader_frames = {"600519.SH": _frame([(_CN_A_DAY, target_bar)])} if target_bar else {}
    ch_frames = {"600519.SH": _frame([(_CN_A_PREV, prev_bar)])} if prev_bar else {}
    return {
        "loader": FakeLoader(loader_frames, "tencent"),
        "ch_client": FakeChClient(ch_frames),
        "calendar_client": FakeCalendarClient((_CN_A_DAY,)),
        "limits_client": None,  # heuristic band (the cn_a golden path)
    }


# ── orders-mode success document ──


def test_orders_mode_returns_the_success_document() -> None:
    text = run_paper_trade_step(_payload(), **_cn_a_fakes())
    doc = json.loads(text)
    assert doc["schema_version"] == "pt-v1.1"
    assert doc["tool"] == "paper_trade_step"
    assert doc["account_id"] == "pa_t6"
    assert doc["market"] == "cn_a"
    assert doc["range"] == {"from": _CN_A_DAY, "to": _CN_A_DAY}
    assert _SHA_RE.match(doc["received_state_hash"])
    # Hand-computed cn_a cents (the T3/T5 golden): buy 100 @ 1421.0, fee 36.95.
    assert doc["fills"][0] == {
        "trade_date": _CN_A_DAY, "symbol": "600519.SH", "side": "buy",
        "qty": 100.0, "price": 1421.0, "fee": 36.95, "reason": "",
    }
    assert doc["end_state"]["cash"] == 57863.05
    assert doc["data_provenance"]["source"] == "clickhouse+tencent(merged)"
    assert validate_payload(doc, load_contract_schema("result")) == []


def test_success_document_is_byte_deterministic_across_runs() -> None:
    first = run_paper_trade_step(_payload(), **_cn_a_fakes())
    second = run_paper_trade_step(_payload(), **_cn_a_fakes())
    assert first == second


# ── AM-5 in-band PAPER_DATA_NOT_READY envelope ──


def test_target_day_without_a_bar_returns_in_band_not_ready() -> None:
    # Neither leg serves the target day → readiness fails → in-band envelope.
    fakes = _cn_a_fakes(target_bar=None, prev_bar=1418.0)
    doc = json.loads(run_paper_trade_step(_payload(), **fakes))
    assert doc["status"] == "error"
    assert doc["code"] == "PAPER_DATA_NOT_READY"
    assert doc["account_id"] == "pa_t6"  # verbatim even on error (AM-4-4)
    assert doc["market"] == "cn_a"
    assert doc["range"] == {"from": _CN_A_DAY, "to": _CN_A_DAY}
    assert _SHA_RE.match(doc["received_state_hash"])  # state was parseable
    assert f"target bar {_CN_A_DAY} not available" in doc["message"]
    assert validate_payload(doc, load_contract_schema("error_envelope")) == []


# ── INVALID_REQUEST: shape parse, semantic gate, range rules ──


def test_malformed_market_is_invalid_request_echoed_verbatim() -> None:
    doc = json.loads(run_paper_trade_step(_payload(market="xyz")))
    assert doc["status"] == "error"
    assert doc["code"] == "INVALID_REQUEST"
    # T5 decision 5: the raw malformed market is echoed verbatim (honest
    # reporting), so the envelope's own market enum is the single degraded
    # case — the only validation error is the market enum.
    assert doc["market"] == "xyz"
    assert "market must be one of" in doc["message"]
    # market not in MARKETS → the coverage object is not computable → hash omitted.
    assert "received_state_hash" not in doc
    errors = validate_payload(doc, load_contract_schema("error_envelope"))
    assert errors and all("market" in e for e in errors)


def test_missing_account_id_is_invalid_request_with_empty_echo() -> None:
    payload = _payload()
    del payload["account_id"]
    doc = json.loads(run_paper_trade_step(payload))
    assert doc["code"] == "INVALID_REQUEST"
    assert doc["account_id"] == ""  # non-string degrades to "" (never leaks)
    assert "account_id" in doc["message"]


def test_non_dict_payload_is_invalid_request() -> None:
    doc = json.loads(run_paper_trade_step(["not", "an", "object"]))
    assert doc["code"] == "INVALID_REQUEST"
    assert doc["account_id"] == "" and doc["market"] == ""
    assert "received_state_hash" not in doc


def test_both_orders_and_strategy_path_violates_the_xor_gate() -> None:
    payload = _payload(strategy_path="agent/strategies/x.py")
    doc = json.loads(run_paper_trade_step(payload))
    assert doc["code"] == "INVALID_REQUEST"
    assert "got both" in doc["message"]
    assert doc["account_id"] == "pa_t6" and doc["market"] == "cn_a"


def test_neither_orders_nor_strategy_path_violates_the_xor_gate() -> None:
    payload = _payload(orders=None)
    doc = json.loads(run_paper_trade_step(payload))
    assert doc["code"] == "INVALID_REQUEST"
    assert "got neither" in doc["message"]


def test_reversed_range_is_invalid_request() -> None:
    # hk avoids the cn_a connector; fetch_market_data guards from > to first.
    payload = _payload(market="hk", from_date=_HK_DAY, to_date="2026-10-15",
                       fee_model=dict(_HK_FEES),
                       orders=[{"symbol": "00700.HK", "side": "buy", "qty": 100}])
    doc = json.loads(run_paper_trade_step(payload))
    assert doc["code"] == "INVALID_REQUEST"
    assert "from_date" in doc["message"] and "to_date" in doc["message"]


def test_orders_mode_multiday_is_invalid_request() -> None:
    # AM-3 single-day gate lives in the engine and surfaces as in-band material.
    payload = _payload(market="hk", from_date="2026-10-15", to_date=_HK_DAY,
                       fee_model=dict(_HK_FEES),
                       orders=[{"symbol": "00700.HK", "side": "buy", "qty": 100}])
    loader = FakeLoader({"00700.HK": _frame([("2026-10-15", 416.0), (_HK_DAY, 417.8)])}, "tencent")
    doc = json.loads(run_paper_trade_step(payload, loader=loader))
    assert doc["code"] == "INVALID_REQUEST"
    assert "from_date == to_date" in doc["message"]


# ── AM-4-1: received_state_hash covers the RAW account_state ──


def _hk_success_hash(account_state: dict) -> str:
    payload = _payload(market="hk", account_state=account_state, from_date=_HK_DAY,
                       to_date=_HK_DAY, fee_model=dict(_HK_FEES),
                       orders=[{"symbol": "00700.HK", "side": "buy", "qty": 100}])
    loader = FakeLoader({"00700.HK": _frame([(_HK_DAY, 417.8)])}, "tencent")
    doc = json.loads(run_paper_trade_step(payload, loader=loader))
    assert "received_state_hash" in doc, doc
    return doc["received_state_hash"]


def test_added_account_state_key_changes_the_hash() -> None:
    base = _hk_success_hash({"cash": 100000.0, "positions": []})
    with_extra = _hk_success_hash({"cash": 100000.0, "positions": [], "note": "llm-added"})
    assert base != with_extra  # the raw value is hashed, not the parsed reconstruction


def test_int_float_respelling_does_not_change_the_hash() -> None:
    as_float = _hk_success_hash({"cash": 100000.0, "positions": []})
    as_int = _hk_success_hash({"cash": 100000, "positions": []})
    assert as_float == as_int  # JCS number canonicalization (state_hash)


# ── strategy_path routing into the lazily-imported T7 module ──


def test_strategy_path_routes_to_run_strategy_path(monkeypatch: pytest.MonkeyPatch) -> None:
    recorded: dict = {}

    def _fake_run_strategy_path(**kwargs):
        recorded.update(kwargs)
        request = kwargs["request"]
        return engine.MatchOutcome(
            end_state=request.account_state,
            effective_fee_model=state_hash.effective_fee_model(request.market, dict(request.fee_model)),
            data_provenance=kwargs["market_data"].provenance,
        )

    universe_calls: list = []

    def _fake_strategy_universe(path):
        universe_calls.append(path)
        return ()

    fake_module = types.ModuleType("src.tools.paper_trade.strategy_exec")
    fake_module.run_strategy_path = _fake_run_strategy_path
    fake_module.strategy_universe = _fake_strategy_universe
    monkeypatch.setitem(sys.modules, "src.tools.paper_trade.strategy_exec", fake_module)

    payload = _payload(market="hk", orders=None, strategy_path="agent/strategies/x.py",
                       from_date=_HK_DAY, to_date=_HK_DAY, fee_model=dict(_HK_FEES),
                       account_state={"cash": 100000.0,
                                      "positions": [{"symbol": "00700.HK", "qty": 100, "avg_cost": 400.0}]})
    loader = FakeLoader({"00700.HK": _frame([(_HK_DAY, 417.8)])}, "tencent")
    doc = json.loads(run_paper_trade_step(payload, loader=loader, timeout_seconds=12.5))

    # The T7 seam receives exactly the contracted kwargs.
    assert set(recorded) == {
        "request", "market_data", "calendar_client", "limits_client",
        "corporate_action_unresolved_by_day", "hk_lot_sizes", "timeout_seconds",
    }
    assert recorded["request"].strategy_path == "agent/strategies/x.py"
    assert recorded["timeout_seconds"] == 12.5
    assert recorded["calendar_client"] is None  # hk zero-calendar (AM-6)
    # The universe prefetch seam was consulted exactly once, with the request's
    # strategy_path; a () declaration keeps the positions-only fetch universe.
    assert universe_calls == ["agent/strategies/x.py"]
    assert recorded["market_data"].symbols == ("00700.HK",)
    # The fake outcome is assembled into the success document.
    assert doc["tool"] == "paper_trade_step" and doc["market"] == "hk"
    assert validate_payload(doc, load_contract_schema("result")) == []


def test_orders_mode_never_consults_strategy_universe(monkeypatch: pytest.MonkeyPatch) -> None:
    # The UNIVERSE prefetch is strategy_path-mode ONLY: orders mode derives its
    # universe from positions ∪ orders and must never touch the T7 module (the
    # fake below lacks run_strategy_path entirely, so any import of it fails).
    def _boom(path):
        raise AssertionError("orders mode must not consult strategy_universe")

    fake_module = types.ModuleType("src.tools.paper_trade.strategy_exec")
    fake_module.strategy_universe = _boom
    monkeypatch.setitem(sys.modules, "src.tools.paper_trade.strategy_exec", fake_module)

    payload = _payload(market="hk", from_date=_HK_DAY, to_date=_HK_DAY,
                       fee_model=dict(_HK_FEES),
                       orders=[{"symbol": "00700.HK", "side": "buy", "qty": 100}])
    loader = FakeLoader({"00700.HK": _frame([(_HK_DAY, 417.8)])}, "tencent")
    doc = json.loads(run_paper_trade_step(payload, loader=loader))
    assert "status" not in doc  # success document, not an error envelope
    assert doc["fills"][0]["symbol"] == "00700.HK"


# ── strategy_path end-to-end: declared UNIVERSE prefetch (T6×T7 integration) ──


def _synth_frame() -> pd.DataFrame:
    document = json.loads(_SYNTH_FIXTURE.read_text(encoding="utf-8"))
    frame = pd.DataFrame(document["bars"])
    frame["trade_date"] = pd.to_datetime(frame["date"])
    return frame.set_index("trade_date")[["open", "high", "low", "close", "volume"]]


def test_strategy_path_cash_only_account_fills_via_declared_universe() -> None:
    # The end-to-end regression for the universe gap: a cash-only account (no
    # positions) + strategy_path (no orders) prefetched an EMPTY universe, so
    # the golden SMA strategy saw no symbols and the call "succeeded" with
    # zero fills.  The fixture's declared UNIVERSE = ("SYNTH-4TO1",) must
    # reach the fetch universe through the real T6 → T7 → engine chain (no
    # strategy_exec fake here; the child really spawns).
    root = get_runtime_root() / "strategies"
    root.mkdir(parents=True, exist_ok=True)
    strategy = root / "golden_sample_sma.py"
    strategy.write_text(_GOLDEN_STRATEGY.read_text(encoding="utf-8"), encoding="utf-8")

    payload = _payload(
        market="us", orders=None, strategy_path=str(strategy),
        account_state={"cash": 50000.0, "positions": []},
        from_date=_US_DAY, to_date=_US_DAY, fee_model=dict(_US_FEES),
    )
    loader = FakeLoader({"SYNTH-4TO1": _synth_frame()}, "sina")
    doc = json.loads(run_paper_trade_step(payload, loader=loader))

    assert "status" not in doc, doc  # success document, not an error envelope
    # Hand-computed us golden: close 128.5, fee max(100×0.0049, 0.99) = 0.99;
    # cash 50000 − 12850.00 − 0.99 = 37099.01 (mirrors the direct T7 gate).
    assert doc["fills"] == [{
        "trade_date": _US_DAY, "symbol": "SYNTH-4TO1", "side": "buy",
        "qty": 100.0, "price": 129.0, "fee": 0.99,
        "reason": "golden sma5 127.5000 > sma20 123.7500",
    }]
    assert doc["end_state"]["cash"] == 37099.01
    assert [(p["symbol"], p["qty"]) for p in doc["end_state"]["positions"]] == [
        ("SYNTH-4TO1", 100.0)]
    assert validate_payload(doc, load_contract_schema("result")) == []


# ── the hand-written MCP wrapper (VD-12) ──


def _mcp_wrapper():
    import mcp_server

    return mcp_server, (
        getattr(mcp_server.paper_trade_step, "fn", None)
        or getattr(mcp_server.paper_trade_step, "__wrapped__", mcp_server.paper_trade_step)
    )


def test_mcp_wrapper_builds_the_payload_and_delegates(monkeypatch: pytest.MonkeyPatch) -> None:
    captured: dict = {}

    def _recorder(payload, **kwargs):
        captured["payload"] = payload
        captured["kwargs"] = kwargs
        return "SENTINEL"

    monkeypatch.setattr(tool_module, "run_paper_trade_step", _recorder)
    _mcp_server, wrapper = _mcp_wrapper()
    out = wrapper(
        account_id="pa_mcp", market="hk",
        account_state={"cash": 1.0, "positions": []},
        from_date=_HK_DAY, to_date=_HK_DAY,
        orders=[{"symbol": "00700.HK", "side": "buy", "qty": 100}],
        fee_model={"commission_min": 3.0},
    )
    assert out == "SENTINEL"
    payload = captured["payload"]
    assert payload["account_id"] == "pa_mcp" and payload["market"] == "hk"
    assert payload["orders"] == [{"symbol": "00700.HK", "side": "buy", "qty": 100}]
    assert payload["fee_model"] == {"commission_min": 3.0}
    # Optional keys absent from the call are absent from the payload (never null).
    assert "strategy_path" not in payload


def test_mcp_wrapper_omits_absent_optional_keys(monkeypatch: pytest.MonkeyPatch) -> None:
    captured: dict = {}

    def _recorder(payload, **kwargs):
        captured["payload"] = payload
        return "X"

    monkeypatch.setattr(tool_module, "run_paper_trade_step", _recorder)
    _mcp_server, wrapper = _mcp_wrapper()
    wrapper(account_id="a", market="us", account_state={"cash": 0.0, "positions": []},
            from_date=_HK_DAY, to_date=_HK_DAY)
    payload = captured["payload"]
    assert "orders" not in payload and "strategy_path" not in payload and "fee_model" not in payload


def test_mcp_wrapper_description_carries_the_frozen_phrase() -> None:
    mcp_server, _wrapper = _mcp_wrapper()
    phrase = "deterministic paper-trading matching engine; never places real orders"
    assert phrase in (mcp_server.paper_trade_step.__doc__ or "")
    assert phrase in PaperTradeStepTool.description


def test_mcp_wrapper_end_to_end_matches_the_core_offline(monkeypatch: pytest.MonkeyPatch) -> None:
    # Drive the real wrapper → real core for hk, stubbing only the network leg.
    from src.tools.paper_trade import data as data_layer

    monkeypatch.setattr(data_layer, "_resolve_network_loader",
                        lambda *_a, **_k: FakeLoader({"00700.HK": _frame([(_HK_DAY, 417.8)])}, "tencent"))
    _mcp_server, wrapper = _mcp_wrapper()
    via_wrapper = wrapper(
        account_id="pa_e2e", market="hk",
        account_state={"cash": 100000.0, "positions": []},
        from_date=_HK_DAY, to_date=_HK_DAY,
        orders=[{"symbol": "00700.HK", "side": "buy", "qty": 100}],
        fee_model=dict(_HK_FEES),
    )
    via_core = run_paper_trade_step(
        {"account_id": "pa_e2e", "market": "hk",
         "account_state": {"cash": 100000.0, "positions": []},
         "from_date": _HK_DAY, "to_date": _HK_DAY,
         "orders": [{"symbol": "00700.HK", "side": "buy", "qty": 100}],
         "fee_model": dict(_HK_FEES)},
        loader=FakeLoader({"00700.HK": _frame([(_HK_DAY, 417.8)])}, "tencent"),
    )
    assert via_wrapper == via_core
    assert json.loads(via_wrapper)["fills"][0]["fee"] == 55.79  # hk golden cents


# ── research-only red line (REQUIREMENTS R1) ──


def test_tool_module_exposes_no_trading_connector_or_order_surface() -> None:
    source = Path(tool_module.__file__).read_text(encoding="utf-8")
    scoped = re.compile(r"trading_(account|orders|positions|quote|history|check|connections|select|place|cancel)")
    assert not scoped.search(source)
    assert "place_order" not in source and "cancel_order" not in source


def test_tool_is_registered_readonly_and_available() -> None:
    tool = PaperTradeStepTool()
    assert tool.name == "paper_trade_step"
    assert tool.is_readonly is True
    assert tool.check_available() is True
    assert tool.parameters["required"] == [
        "account_id", "market", "account_state", "from_date", "to_date",
    ]
    assert set(tool.parameters["properties"]["market"]["enum"]) == set(MARKETS)


def test_execute_delegates_the_kwargs_payload_to_the_core(monkeypatch: pytest.MonkeyPatch) -> None:
    # execute() carries no injection seams, so stub the core to prove the
    # BaseTool hands its kwargs through as the raw payload dict (offline).
    captured: dict = {}

    def _recorder(payload, **kwargs):
        captured["payload"] = payload
        return "DOC"

    monkeypatch.setattr(tool_module, "run_paper_trade_step", _recorder)
    out = PaperTradeStepTool().execute(
        account_id="a", market="hk", account_state={"cash": 0.0, "positions": []},
        from_date=_HK_DAY, to_date=_HK_DAY, orders=[],
    )
    assert out == "DOC"
    assert captured["payload"]["account_id"] == "a"
    assert captured["payload"]["market"] == "hk"
    assert captured["payload"]["orders"] == []