Quant Trading for Programmers 21: Compress Paper-Trading Results Into A Recommendation Summary

Article 20 could already generate a paper-trading daily report. But that report was still more like a state description than an action summary suitable for reviews and alerts.

Article 21 adds a recommendation summary, compressing risk controls, rebalancing, and position state into one clear action: keep watching, check the rebalance plan, or reduce risk first.

Why Add A Recommendation Summary

A risk report tells you where the problem is. A rebalance plan tells you what may need to be bought or sold. An account snapshot tells you the current state.

All of that matters, but an alert system should not push every internal structure to a person unchanged. What people need to see first every day is one sentence: what should be done today?

In a quant system, this layer is usually not a “trading signal.” It is an “operational action.” A trading signal answers the buy-or-sell direction. An operational action answers whether someone needs to intervene today, whether risk should be reduced, or whether observation can continue. Keeping the two separate prevents the alert system from packaging a technical signal as investment advice.

Recommendation Object

Chapter 21 adds app/recommendations.py.

@dataclass(frozen=True)
class PaperRecommendation:
    action: str
    severity: str
    summary: str
    reasons: tuple[str, ...]
    order_count: int

For now, action stays simple: REDUCE_RISK, REBALANCE, and HOLD.

• REDUCE_RISK: handle blocker-level risk first, such as excessive single-stock concentration or total exposure.
• REBALANCE: there is no blocker-level risk, but a rebalance plan needs review.
• HOLD: there is no obvious risk and no order above the minimum rebalance threshold, so keep watching.

Priority

The key part of the recommendation logic is priority.

Blocker-level risk always outranks rebalance suggestions. If the account has already triggered a single-stock limit or excessive total exposure, the system should not remind you about normal rebalancing while downplaying the risk.

if risk_report.severity == "blocker":
    action = "REDUCE_RISK"
elif rebalance_plan.orders:
    action = "REBALANCE"
else:
    action = "HOLD"

This judgment is plain, but it writes the action boundary of the paper-trading system into code.

Current Integrated Run

The recommendation summary can now be viewed through the shared example command for articles 21-25:

uv run python -m scripts.chapter_examples paper-ops

This command constructs a paper-trading account with two stocks, then runs input checks, state persistence, the daily flow, recommendation summary, review summary, and output checks. The recommendation-summary section looks like this:

In this run, the position weight of 600519.SH reaches 49.90%, exceeding the default single-stock limit, so the recommended action is REDUCE_RISK. Although there is also a rebalance plan, the recommendation layer does not present it as ordinary rebalancing. It prioritizes risk handling.

Chapter Update And Repository

This chapter adds:

• app/recommendations.py.
• A paper-trading recommendation summary object.
• Recommendation actions synthesized from snapshots, risk reports, and rebalance plans.
• An integrated paper-ops example showing recommendation output in a full daily paper-trading flow.
• A clear boundary between recommendation actions and trading signals.
• tests/test_recommendations.py, covering risk priority, rebalance suggestions, and hold actions for an empty account.

Repository:

https://github.com/ax2/zi-quant-platform

Code for this chapter:

git clone https://github.com/ax2/zi-quant-platform.git
cd zi-quant-platform
git checkout chapter-21
uv sync --extra dev
uv run pytest tests/test_recommendations.py

Chapter 21 is commit 8ede593, tagged as chapter-21.

Summary

A recommendation summary is not a return forecast and not investment advice.

Article 21 only organizes the internal paper-trading state into an action summary that people can read more easily. The next article saves these results into daily review records.

WeChat

Follow ZiCode on WeChat

If this post was useful, you can follow later updates on WeChat as well.

X / Twitter

Follow @ax2_zicode

Faster technical notes, short thoughts, and new-post alerts are posted on X.

X Open X Profile @ax2_zicode