[FEATURE] Paper mode in hub: blue palette, banner, sample runner - closes #86 #87

[Ibrahim-3d]

Summary

Pivoted per the discussion below: kept the live-price buy/sell scenario but moved it behind a button inside the hub, plus the visual safety rails @sjackson0109 asked for.

• File menu gains a Paper Mode checkbutton; selection persists in gui_settings.json
• Paper mode paints the hub with a blue palette instead of black
• PAPER TRADING banner across the top + contrasting label inside the Current Trades panel
• Banner hosts a Run sample trade button that pulls a live BTC price from Binance's public ticker and routes a simulated buy then sell through PaperTradingAccount
• Drops the now-redundant standalone demo_paper_trading.py script
• Drops the duplicate async demo_paper_trading() stub at the bottom of pt_paper_trading.py

Closes #86 and #87.

Why this looks like a different PR

Force-pushed to replace the original standalone-script commit with the in-hub integration per the pivot agreement above. Older PR diff is gone from the file list - history is now one commit on top of main.

Implementation notes

• New module app/pt_paper_mode.py owns the palette, banner widget, sample runner, and disk-read helper. Keeps pt_hub.py edits surgical (~190 lines added, all isolated to the menu/theme entry points).
• Paper-mode flag is read straight off disk before the first _apply_forced_dark_mode call so the window does not flash dark before settling on blue.
• The toggle shows a Restart for full effect notice because matplotlib chart facecolors and option_add classic-widget defaults are baked at widget-creation time. Banner and trades-section label toggle live without restart.
• Binance fetch is a 5s public GET with a deterministic fallback path; tests cover happy/missing-key/network-error paths and the buy/sell scenario with and without a live price.

Files

File	Change
app/pt_paper_mode.py	new - palette, banner, sample runner, persistence helper
app/pt_hub.py	settings key, settings-load reorder, palette overlay branch, file-menu toggle, banner build, trades-section label, sample-runner handler
app/pt_paper_trading.py	removed duplicate async demo_paper_trading() stub
app/test_paper_mode.py	new - 14 tests covering palette mirror, disk round-trip, fetch happy/error paths, sample runner with live price + fallback

Local checks

• python -m black --check app/ clean (102 files unchanged)
• python -m flake8 app/pt_paper_mode.py app/test_paper_mode.py --max-line-length=100 --extend-ignore=E203,W503 clean
• python -m flake8 app/pt_hub.py --select=E9,F63,F7,F82 clean (hard-error gate)
• python -m pytest app/test_paper_mode.py app/test_paper_trading_integration.py -q -> 22 passed

Test plan

• Toggle File > Paper Mode off then on - check gui_settings.json flips and a restart paints blue with banner + Current Trades label
• Click Run sample trade with internet on - banner shows live BTC, buy/sell delta is small (commission + drift)
• Click Run sample trade with internet off - banner shows offline (using sim), trade still fills via simulator
• Toggle paper mode off mid-session - banner and label disappear immediately, restart prompt shown

[Ibrahim-3d]

Manual Testing Guide — PR #90: Paper Trading Demo Script

Prerequisites

git fetch fork && git checkout feat/87-paper-trading-demo
cd app

1. Run the demo

python pt_paper_trading_demo.py

Expected: Script runs to completion without errors. Should print a summary of simulated trades, account balance, P&L.

2. Verify it does not touch live APIs

Check output for any Robinhood/Binance connection attempts — there should be none. All prices come from MarketDataSimulator.

3. Sanity check output

• Final balance should be non-negative
• At least one trade executed
• P&L printed (positive or negative is fine)

Rollback

git checkout main -- app/pt_paper_trading_demo.py

[sjackson0109]

Nice idea @Ibrahim-3d - The paper trading system existed beforehand; i've just never needed to test/demo it.

I think the demo should use the same UI, personally. Don't think it massively matters.
Anyone taking a sensible approach to crypto trading, does so at their own risk. Claiming to be a sensible person; one would expect anyone trading would take the smallest amount of risk (manage the potential loss); and slowly increase as they build confidence.
What do you think?

[Ibrahim-3d]

@sjackson0109 yeah you're right, demo should live in the hub. Closing this in favour of doing it properly there.

One thing though — "sensible traders manage their own risk" assumes the user already knows what they're doing. I'm honestly not in that bucket yet, and a few friends I've shown this to aren't either. We'd want to watch it run on paper for a bit before pointing it at real money. The "Paper" label is the trust signal — "just use small sizes" doesn't really replace it for newcomers.

Plus it's useful for us: every time we touch pt_thinker or the risk engine, paper mode is how we'd actually validate the change against live market data without burning cash. And if we ever want to show real numbers ("DCA returned X over Y weeks"), those have to come from paper sessions first.

So proposing:

• Paper / Live toggle in the hub header (already half-wired via pt_gui_integration)
• Persist the mode + visual banner when in Paper so there's no doubt which one you're in
• Move the demo scenario into a "Run sample" button inside Paper mode
• Drop the standalone script

Sound good? Happy to close this PR and open a new one against pt_hub.py.

[Ibrahim-3d]

Going to pivot this PR — keep the live-price + full buy/sell scenario, but wire it into the hub's Paper mode as a "Run sample" button instead of a standalone script. That way the demo lives behind the actual UI like you suggested, and we get rid of the duplicate demo_paper_trading() stub currently sitting inside pt_paper_trading.py.

Will force-push to this branch once it's ready.

[sjackson0109]

How about we consider paper mode changes the CSS of the background. Say BLUE instead of BLACK. So it is blatantly obvious which mode we are in.
And in the trading section, add the words ‘PAPER TRADING’. In a contrasting font colour.
The file menu should have the ‘paper mode’ toggle button. This way users don’t need to be familiar with the CLI.

[sjackson0109]

I see no reason to close/cancel this PR, or just pivot, up to you.

[Ibrahim-3d]

Pivoted into #97 per the discussion above (@sjackson0109's spec: blue palette, PAPER TRADING label in trades section, file-menu toggle). The live BTC + buy/sell scenario now lives behind a Run sample trade button on the in-hub banner, and the duplicate demo_paper_trading() stub in pt_paper_trading.py is gone.

Will close this PR once #97 is merged so the standalone script does not get re-introduced.

[Ibrahim-3d]

Force-pushed the pivot. Standalone demo_paper_trading.py is gone; live BTC + buy/sell now lives behind a Run sample trade button on the in-hub paper banner. File > Paper Mode toggle persists across restarts, blue palette + PAPER TRADING label in Current Trades match the spec from the comment thread above. Local: black clean, flake8 hard-error gate clean, 22 tests pass.

[sjackson0109]

Now that #97 has been merged into development branch - can we cancel this PR? @Ibrahim-3d

[Ibrahim-3d]

@sjackson0109 Small correction: #97 was closed, not merged,

[Ibrahim-3d]

Manual QA guide - Paper Mode (#90)

Manual walkthrough to validate this PR before merge. Covers the File-menu toggle, blue palette + banner, persistence, and the sample-trade runner (Binance live + simulator fallback).

Prerequisites

• Checked out: git fetch fork feat/87-paper-trading-demo && git checkout feat/87-paper-trading-demo
• Deps installed: python -m pip install -r requirements.txt
• Launch the hub: python app/pt_hub.py
• No API keys needed (the sample runner uses Binance's public, unauthenticated ticker)

T1 - Toggle paper mode on

1. Open File menu -> click Paper Mode (checkbutton).
2. Expect: checkmark appears next to the item.

T2 - Visual safety cues

1. With paper mode on, observe the window.
2. Expect:
   • Background switches from the default dark/black to blue (#0A1B3A family).
   • A "PAPER TRADING" banner spans the top, accent in gold (#FFC400) so it stands out.
   • The Current Trades panel shows a contrasting paper label.
3. Pass criteria: impossible to mistake the session for live trading at a glance.

T3 - Persistence across restart

1. Leave paper mode on. Close the hub completely.
2. Inspect gui_settings.json -> key paper_mode_enabled should be true.
3. Relaunch python app/pt_hub.py.
4. Expect: hub reopens already in blue/paper mode, banner present, no manual re-toggle.

T4 - Sample trade, live Binance price (happy path)

1. Ensure internet is reachable.
2. Click Run sample trade in the banner.
3. Expect: result label (right of the button) shows starting balance, final balance, buy price, sell price, and source = binance.
4. Pass criteria: buy/sell prices are near the real BTCUSDT spot; final balance reflects a simulated BUY then SELL round-trip; no real order placed anywhere.

T5 - Sample trade, offline fallback (simulator)

1. Disconnect network (or block api.binance.com).
2. Click Run sample trade.
3. Expect: still completes; result label shows source = simulator (MarketDataSimulator fallback). No crash, no hang.

T6 - Toggle paper mode off

1. File -> Paper Mode again to uncheck.
2. Expect: palette returns to the default dark theme, "PAPER TRADING" banner and paper label disappear, paper_mode_enabled becomes false in gui_settings.json.

T7 - Corrupt/missing settings (negative)

1. Close hub. Replace gui_settings.json contents with garbage (e.g. { broken), or delete the file.
2. Relaunch.
3. Expect: hub starts in default (live/dark) mode without error - missing/garbage settings degrade safely to paper mode OFF.

Pass checklist

• T1 toggle works from File menu
• T2 blue palette + gold "PAPER TRADING" banner + Current Trades label
• T3 setting persists across restart
• T4 sample trade uses live Binance price (source=binance), no real order
• T5 sample trade falls back to simulator offline (source=simulator)
• T6 toggling off fully restores dark/live appearance
• T7 corrupt/missing settings default safely to paper OFF

Automated backstop

python -m pytest app/test_paper_mode.py app/test_paper_trading_integration.py -q (palette mirroring, settings round-trip incl. garbage files, Binance ticker happy/failure, buy/sell with live price + simulator). Currently green in CI.

[sjackson0109]

@Ibrahim-3d has transitioned paper-trading-mode from CLI based to GUI based, with a new blue background to help clearly distinguish between the two modes. This is an increadible achievement in such a short timeframe.