feat: shadow book + shadow-vs-manual performance comparison

The manual paper book only contains trades taken by hand, inside a 20 minute window, on days someone was available. The backtest that validated this strategy auto-takes the top-ranked qualified setups up to capacity every session. The forward record was therefore measuring strategy plus discretion plus availability -- and degrading silently on busy days. The shadow book closes that gap: it mirrors the backtest's selection rule (top strategy_rank qualified, up to capacity, 1% fixed-fractional risk) and shares the manual book's exit policy, so the only difference between the two books is which setups get taken. Selection ordering reuses the strategy_rank the scanner already stores rather than recomputing it, so the two cannot drift apart. It runs as a near-close pipeline step right after the scan, marking entries at the same prices a human would see. Gate-reset re-entry state is now scoped per book -- the books diverge as soon as their entries differ, and each must see only its own stops. Performance view rewritten around the comparison: - three series (shadow, manual, SPY) from a new endpoint - SPY changes from a per-trade cost-basis counterfactual to plain buy-and-hold %, since one line has to serve two books - headline stats are R-multiples, not currency: the books size differently, so only R compares across them - configurable start date, because the strategy has been revised repeatedly and pre-cutover trades ran under rules that no longer exist Migration 024 also repairs the numeric weekday crons written by 023, rewriting only rows still holding the broken form so hand-corrected settings survive. Its literals are inlined because bound parameters render as NULL under 'alembic upgrade --sql'. The shadow book is opt-in and writes nothing until enabled. Verify its first selections match a backtest of that day's cross-section before trusting any point on the curve. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-20 23:44:41 +02:00
parent 29715ef3d1
commit ba2df8b9fd
17 changed files with 1334 additions and 40 deletions
@@ -0,0 +1,101 @@
+"""Performance comparison: per-book series, R-multiples, and the start-date window."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+from types import SimpleNamespace
+
+import pytest
+
+from app.services import paper_trade_service as pts
+from app.services.trade_policy import MANUAL_BOOK, SHADOW_BOOK
+
+
+def _trade(*, book, entry=100.0, stop=95.0, close=None, shares=10.0, opened_days_ago=5):
+    now = datetime.now(timezone.utc)
+    return SimpleNamespace(
+        ticker_id=1,
+        direction="long",
+        entry_price=entry,
+        stop_loss=stop,
+        shares=shares,
+        book=book,
+        status="closed" if close is not None else "open",
+        close_price=close,
+        opened_at=now - timedelta(days=opened_days_ago),
+        closed_at=now if close is not None else None,
+    )
+
+
+class TestRMultiple:
+    def test_winner_measured_in_units_of_initial_risk(self):
+        # Entry 100, stop 95 → 5 of risk. Exit 115 → +15 → +3R.
+        trade = _trade(book=SHADOW_BOOK, close=115.0)
+        assert pts.trade_r_multiple(trade, None) == pytest.approx(3.0)
+
+    def test_full_stop_is_minus_one_r(self):
+        trade = _trade(book=SHADOW_BOOK, close=95.0)
+        assert pts.trade_r_multiple(trade, None) == pytest.approx(-1.0)
+
+    def test_open_trade_marks_to_the_latest_close(self):
+        trade = _trade(book=SHADOW_BOOK)
+        assert pts.trade_r_multiple(trade, 110.0) == pytest.approx(2.0)
+
+    def test_no_risk_distance_has_no_r(self):
+        trade = _trade(book=SHADOW_BOOK, entry=100.0, stop=100.0, close=120.0)
+        assert pts.trade_r_multiple(trade, None) is None
+
+
+class TestBookStats:
+    def test_r_is_independent_of_position_size(self):
+        """The whole point: a 10-share and a 1000-share book compare equally."""
+        small = pts.book_stats([_trade(book=SHADOW_BOOK, close=115.0, shares=10)], {})
+        large = pts.book_stats([_trade(book=MANUAL_BOOK, close=115.0, shares=1000)], {})
+        assert small["total_r"] == large["total_r"] == pytest.approx(3.0)
+
+    def test_counts_and_win_rate(self):
+        trades = [
+            _trade(book=SHADOW_BOOK, close=115.0),
+            _trade(book=SHADOW_BOOK, close=95.0),
+            _trade(book=SHADOW_BOOK),
+        ]
+        stats = pts.book_stats(trades, {1: 110.0})
+        assert stats["trades"] == 3
+        assert stats["closed"] == 2
+        assert stats["open"] == 1
+        # +3R, -1R, +2R marked → 2 of 3 positive.
+        assert stats["win_rate"] == pytest.approx(66.7)
+        assert stats["total_r"] == pytest.approx(4.0)
+
+
+class TestPerformanceStartDate:
+    @pytest.fixture
+    async def session(self):
+        from tests.conftest import _test_session_factory
+
+        async with _test_session_factory() as session:
+            yield session
+
+    @pytest.mark.asyncio
+    async def test_unset_means_all_history(self, session):
+        assert await pts.get_performance_start(session) is None
+
+    @pytest.mark.asyncio
+    async def test_reads_an_iso_date(self, session):
+        await pts.settings_store.upsert_setting(
+            session, pts.KEY_PERFORMANCE_START, "2026-07-20"
+        )
+        assert await pts.get_performance_start(session) == date(2026, 7, 20)
+
+    @pytest.mark.asyncio
+    async def test_garbage_falls_back_to_all_history(self, session):
+        """A bad setting must not blank the whole performance card."""
+        await pts.settings_store.upsert_setting(
+            session, pts.KEY_PERFORMANCE_START, "not-a-date"
+        )
+        assert await pts.get_performance_start(session) is None
+
+    @pytest.mark.asyncio
+    async def test_empty_string_means_all_history(self, session):
+        await pts.settings_store.upsert_setting(session, pts.KEY_PERFORMANCE_START, "")
+        assert await pts.get_performance_start(session) is None
@@ -0,0 +1,189 @@
+"""Shadow book selection, sizing and book isolation.
+
+The shadow book only has evidentiary value if it selects what the backtest
+would select: top-ranked qualified setups, up to capacity, skipping held names
+and post-stop gate-reset lockouts. These tests pin that contract.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from app.models.paper_trade import PaperTrade
+from app.models.ticker import Ticker
+from app.models.trade_setup import TradeSetup
+from app.models.user import User
+from app.services import shadow_book_service
+from app.services.trade_policy import MANUAL_BOOK, SHADOW_BOOK, get_reentry_gate_locks
+
+
+@pytest.fixture
+async def session():
+    from tests.conftest import _test_session_factory
+
+    async with _test_session_factory() as session:
+        yield session
+
+
+# Floors the gate applies; every setup below clears them so tests exercise
+# ranking rather than qualification.
+_CONFIG = {
+    "min_rr": 2.0,
+    "min_confidence": 0.0,
+    "min_momentum_percentile": 80.0,
+    "exclude_neutral": False,
+}
+
+
+async def _seed(session, symbols: list[str]) -> dict[str, int]:
+    session.add(User(id=1, username="owner", password_hash="x"))
+    ids: dict[str, int] = {}
+    for i, symbol in enumerate(symbols, start=1):
+        ticker = Ticker(id=i, symbol=symbol, name=symbol)
+        session.add(ticker)
+        ids[symbol] = i
+    await session.commit()
+    return ids
+
+
+def _setup(ticker_id: int, *, rank: float, detected: datetime, entry=100.0, stop=95.0):
+    target = entry + 3 * (entry - stop)
+    return TradeSetup(
+        ticker_id=ticker_id,
+        direction="long",
+        entry_price=entry,
+        stop_loss=stop,
+        target=target,
+        rr_ratio=3.0,
+        composite_score=70.0,
+        confidence_score=70.0,
+        detected_at=detected,
+        strategy_rank=rank,
+        momentum_percentile=90.0,
+        recommended_action="buy",
+        targets_json=json.dumps(
+            [{"price": target, "probability": 45.0, "is_primary": True, "rr": 3.0}]
+        ),
+    )
+
+
+class TestSizing:
+    def test_risks_one_percent_down_to_the_stop(self):
+        shares = shadow_book_service.position_shares(100_000, 1.0, 100.0, 95.0)
+        assert shares == pytest.approx(200.0)  # $1,000 risk / $5 per share
+
+    def test_zero_risk_distance_takes_no_position(self):
+        assert shadow_book_service.position_shares(100_000, 1.0, 100.0, 100.0) == 0.0
+
+
+class TestSelection:
+    @pytest.mark.asyncio
+    async def test_takes_top_ranked_up_to_capacity(self, session):
+        ids = await _seed(session, ["AAA", "BBB", "CCC"])
+        now = datetime.now(timezone.utc)
+        session.add_all(
+            [
+                _setup(ids["AAA"], rank=0.10, detected=now),
+                _setup(ids["BBB"], rank=0.90, detected=now),
+                _setup(ids["CCC"], rank=0.50, detected=now),
+            ]
+        )
+        await session.commit()
+        await shadow_book_service.settings_store.upsert_setting(
+            session, shadow_book_service.KEY_CAPACITY, "2"
+        )
+
+        summary = await shadow_book_service.open_shadow_positions(
+            session, activation_config=_CONFIG
+        )
+
+        assert summary["opened"] == 2
+        # Highest strategy_rank first — the backtest's ordering key.
+        assert summary["symbols"] == [ids["BBB"], ids["CCC"]]
+
+    @pytest.mark.asyncio
+    async def test_skips_names_already_held(self, session):
+        ids = await _seed(session, ["AAA", "BBB"])
+        now = datetime.now(timezone.utc)
+        session.add_all(
+            [_setup(ids["AAA"], rank=0.9, detected=now), _setup(ids["BBB"], rank=0.5, detected=now)]
+        )
+        session.add(
+            PaperTrade(
+                user_id=1, ticker_id=ids["AAA"], direction="long", entry_price=100.0,
+                shares=10.0, stop_loss=95.0, target=115.0, status="open",
+                opened_at=now, book=SHADOW_BOOK,
+            )
+        )
+        await session.commit()
+
+        summary = await shadow_book_service.open_shadow_positions(
+            session, activation_config=_CONFIG
+        )
+
+        assert summary["skipped_held"] == 1
+        assert summary["symbols"] == [ids["BBB"]]
+
+    @pytest.mark.asyncio
+    async def test_respects_post_stop_gate_lock(self, session):
+        ids = await _seed(session, ["AAA"])
+        now = datetime.now(timezone.utc)
+        session.add(_setup(ids["AAA"], rank=0.9, detected=now))
+        # Stopped out and never requalified — locked out of re-entry.
+        session.add(
+            PaperTrade(
+                user_id=1, ticker_id=ids["AAA"], direction="long", entry_price=100.0,
+                shares=10.0, stop_loss=95.0, target=115.0, status="closed",
+                opened_at=now - timedelta(days=5), closed_at=now - timedelta(days=1),
+                close_price=95.0, close_reason="stop", book=SHADOW_BOOK,
+            )
+        )
+        await session.commit()
+
+        summary = await shadow_book_service.open_shadow_positions(
+            session, activation_config=_CONFIG
+        )
+
+        assert summary["opened"] == 0
+        assert summary["skipped_locked"] == 1
+
+
+class TestBookIsolation:
+    @pytest.mark.asyncio
+    async def test_gate_locks_do_not_leak_between_books(self, session):
+        """A manual stop must not lock the shadow book out of the same name."""
+        ids = await _seed(session, ["AAA"])
+        now = datetime.now(timezone.utc)
+        session.add(
+            PaperTrade(
+                user_id=1, ticker_id=ids["AAA"], direction="long", entry_price=100.0,
+                shares=10.0, stop_loss=95.0, target=115.0, status="closed",
+                opened_at=now - timedelta(days=5), closed_at=now - timedelta(days=1),
+                close_price=95.0, close_reason="stop", book=MANUAL_BOOK,
+            )
+        )
+        await session.commit()
+
+        assert ids["AAA"] in await get_reentry_gate_locks(session, book=MANUAL_BOOK)
+        assert ids["AAA"] not in await get_reentry_gate_locks(session, book=SHADOW_BOOK)
+
+    @pytest.mark.asyncio
+    async def test_shadow_equity_ignores_manual_pnl(self, session):
+        ids = await _seed(session, ["AAA"])
+        now = datetime.now(timezone.utc)
+        session.add(
+            PaperTrade(
+                user_id=1, ticker_id=ids["AAA"], direction="long", entry_price=100.0,
+                shares=100.0, stop_loss=95.0, target=115.0, status="closed",
+                opened_at=now - timedelta(days=5), closed_at=now,
+                close_price=150.0, close_reason="trailing", book=MANUAL_BOOK,
+            )
+        )
+        await session.commit()
+
+        equity = await shadow_book_service.current_equity(session, 100_000.0)
+
+        assert equity == 100_000.0