How I built
AI Trading PK

Milestones, newest first

Every time we ship something meaningful, an entry lands here. Pre-existing sections below are updated in place when behaviour changes.

The pitch in one paragraph

If someone gives you 30 seconds, this is what you say.

Why it exists

Five concepts to know

If you understand these, you can answer almost any question someone throws at you.

The architecture in one diagram

Five layers, one direction of dependency. Nothing fancy.

Stack, layer by layer

Why each piece is here, in one or two lines.

The engine tick

One function — advance_one_trading_day in backend/app/engine/tick.py — runs the same six steps in the same order every day. Idempotent. No exceptions.

No look-ahead, or it's all a lie

The single bug that ruins every amateur backtest: accidentally using future data in a "past" decision. This system has a test that fails loudly if you trip it.

# backend/tests/test_engine_no_lookahead.py — the heart of the safety net

def test_decision_never_reads_future_data(db):
    # day 1..3 prices are 600..602; day 4 jumps to 999 (the "future")
    seed_path_bars(db, ticker="2330.TW", start=date(2026, 5, 4),
                   opens=[600, 601, 602, 999, 1000, 1001])

    snoop = SnoopProvider()
    advance_one_trading_day(db, comp, snoop, _snoop_snapshot)
    advance_one_trading_day(db, comp, snoop, _snoop_snapshot)
    advance_one_trading_day(db, comp, snoop, _snoop_snapshot)

    # for every decision, the dates it saw must be ≤ its own decision date
    for dk_observed, seen in snoop.observations:
        assert all(d <= dk_observed for d in seen), \
            f"Decision on {dk_observed} saw future dates {seen}"

Every refactor that touches the engine runs this test. If someone ever "optimizes" by reading tomorrow's open while making today's decision, the test breaks. The bug can't ship.

Strategy schema: two halves

A single shape, half code-enforced, half plain language. Personas are just named presets of this shape.

{
  "max_position_pct": 0.30,
  "max_holdings": 4,
  "max_trades_per_decision": 3,
  "cash_floor_pct": 0.10,
  "stop_loss_pct": 0.08,
  "take_profit_pct": 0.20
}

"Lock in 5-day and 20-day momentum
leaders that are above MA20. Cut
positions down -8%. Take profit at
+20% in tranches. When momentum
fades, rotate immediately."

Why both: structured alone is too rigid to feel like a personality. free_text alone lets the LLM over-trade and bleed out on fees. Splitting them gives you the upside of natural-language configuration with the safety of engine-enforced limits.

"是怎麼建立 agent 的？" — clearing this up

Coworkers often ask if agents are markdown config files. They are not. Here is the precise mental model so you can answer with confidence.

# The actual creation flow — UI under the hood

POST /competitions/1/agents
{
  "owner_name": "Jazz",
  "name": "技術線仙 v3",
  "model_provider": "claude",
  "persona_id": "ta_charter",
  "decision_cadence_days": 1,
  "strategy": {
    "structured": { ...numeric guardrails... },
    "free_text": "在 above_ma20 且 volume_ratio > 1.5 時進場..."
  }
}

Why the UI route exists: the brief was non-engineers configure agents. Forcing them to edit YAML files would defeat the entire point. The new-agent flow is: quiz → persona pick → tweak structured caps → write free_text → connect Claude → submit.

The 個股 / Stocks tab

The leaderboard answers "who's winning?". The Stocks tab answers "what should I tell my agent to look at?". Added so users can browse the universe before tweaking their strategy.

# backend/app/api/stocks.py — the endpoint reuses the LLM's snapshot

@router.get("/competitions/{competition_id}/stocks")
def list_competition_stocks(competition_id, as_of, db):
    universe = universe_for_competition(db, competition_id)
    on = as_of or latest_finalized_date(db, universe)
    rows = build_snapshot(db, universe, on)   # <-- same fn the engine uses
    # attach 30-day sparkline so the table can render without N round-trips
    ...
    return rows

Why this matters for the PK: non-engineers writing free_text strategies tend to write "buy stocks that go up." Showing them the actual snapshot the LLM sees turns vague intuition into specific instructions — "buy stocks with pct_5d > 10% and volume_ratio > 1.5" — which the LLM can actually execute.

三大法人 (institutional flows)

Every Taiwan trader checks 三大法人 numbers before they trade. If our agents don't see them, they're blind to the single biggest moving force in the market.

How the LLM sees it. Each row in the snapshot now carries foreign_net_lots, trust_net_lots, dealer_net_lots, total_inst_net_lots alongside the price + volume fields. Units are 張 (1 張 = 1000 shares) for readability. Positive = net buy, negative = net sell. The system prompt explicitly tells the LLM what to look for — "三大法人 buying with rising price = strong signal; selling into rallies = caution; investment trust (投信) consistently buying = often a multi-day move".

# Verified: 2454 聯發科 on 2026-05-29

ticker: 2454.TW
last_close: 4310.0       # was 4410 day before
pct_1d: -2.27%           # the drop
foreign_net_lots: -2325   # 外資 dumped 2.3M shares
trust_net_lots: -1021     # 投信 sold 1M shares
dealer_net_lots: -130     # 自營 small sell
total_inst_net_lots: -3476  # 三大法人 sum: 3.5M sell

The data sources: https://www.twse.com.tw/rwd/zh/fund/T86 (TSE) and https://www.tpex.org.tw/web/stock/3insti/daily_trade/3itrade_hedge_result.php (OTC). Both free, both work, both updated within 30 min of market close. One HTTP call covers the entire market — so refreshing 三大法人 for our 194-ticker universe is just 2 requests per day.

Risk-adjusted leaderboard

Three metrics turn the leaderboard from "who got luckiest" into "who actually traded well". Toggle the ranking by Return / Sharpe / Max Drawdown.

Why this matters. Watch what happened in our own demo when we re-ranked:

Momentum's raw return is nearly double, but Contrarian put up its smaller gain with one-third the drawdown — so on a risk-adjusted basis, Contrarian wins. This is the kind of comparison that turns the leaderboard from a slot machine into something you can actually defend in front of finance-literate coworkers.

Implementation in backend/app/services/metrics.py. Annualized using 252 trading days. Returns None on insufficient data (fewer than 2 snapshots, or zero volatility) — frontend renders that as "—" rather than fabricating a value.

How "real-time" actually works here

Two different data streams power the app. The boundary between them is the most important architectural decision after the engine-as-source-of-truth choice.

The boundary in one sentence: live data is paint on top of the UI. Anything that mutates the portfolio (orders, fills, MTM snapshots) reads only daily data, so the engine stays deterministic and the no-look-ahead test still passes.

Why not push intraday into decisions? Two reasons. (1) A decision made at 11am using 11am prices can't fill at 11am — paper or real — so you'd need to invent a fill model that approximates VWAP or next-quote, and your backtest stops being trustworthy. (2) The no-look-ahead test is what makes me confident showing the dashboard to clients. Once you mix time scales, that confidence is gone and the bug surface grows.

BYOK Claude: how user keys work

No shared Anthropic key. Each person connects their own.

# backend/app/services/crypto.py — the encryption seam

def _derive_key(secret: str) -> bytes:
    digest = hashlib.sha256(secret.encode("utf-8")).digest()
    return base64.urlsafe_b64encode(digest)

def encrypt(plaintext: str) -> bytes:
    return _fernet().encrypt(plaintext.encode("utf-8"))

def decrypt(token: bytes) -> str:
    return _fernet().decrypt(token).decode("utf-8")

If the user disconnects, the row is deleted. If the user's key is stored but invalid, the LLM call fails gracefully — the decision logs "claude not connected" and returns zero orders. The engine never crashes mid-tick.

The 賽馬場 UI redesign

The first version was a clean dark table — readable, dull. The redesign was a deliberate borrowing of horse-race energy. Six moves did most of the work.

Six decisions, and why I made them

If someone asks "why didn't you use X?", these are your answers.

What it costs to run

Be ready when someone asks about the bill.

Bottom line: even at "10 users daily for a year", total bill is a coffee per month. The BYOK split moves Claude costs to each user's own account — the system itself only pays for Gemini calls.

What I'd build next

Talking points

Punchy sentences I can actually say. Each one is under 30 words. Paraphrase, don't quote word-for-word. You built this — talk about it like you built it.

How to use this doc