mbrucedogs/maneshtrader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
274c60f8e6
maneshtrader/ONBOARDING.md

12 KiB
Raw Blame History

ManeshTrader Onboarding

1) What This Tool Does

ManeshTrader analyzes OHLC candles and labels each closed bar as:

  • real_bull: close is above previous high (or previous body high if wick filter is enabled)
  • real_bear: close is below previous low (or previous body low if wick filter is enabled)
  • fake: close is inside previous range (noise)

Trend logic:

  • 2 consecutive real bullish bars => bullish trend active
  • 2 consecutive real bearish bars => bearish trend active
  • Reversal requires 2 consecutive opposite real bars
  • Fake bars do not reverse trend

In-app help popup:

  • Open from sidebar Help / Quick Start
  • Uses a multi-screen, child-friendly guide implemented in web/src/web_core/ui/help_content.py
  • Includes dedicated screens for core setup, filters, training mode, backtest controls, and advanced panels

Beginner interpretation panel:

  • Main page always shows What This Tool Means (Beginner Training)
  • Includes plain-English definitions of top metrics and a historical snapshot table for 1M, 3M, 6M, 1Y
  • Each row includes a simple interpretation so non-traders can quickly understand whether a window was directional or noisy

2) Quick Start (Recommended)

From project root:

./run.sh

This script:

  • creates .venv if needed
  • installs dependencies from requirements.txt
  • launches Streamlit

Then open the shown URL (usually http://localhost:8501).

3) macOS Double-Click Start

In Finder, double-click:

  • Run ManeshTrader.command

If macOS blocks first run, execute once:

xattr -d com.apple.quarantine "Run ManeshTrader.command"

Optional: Build a Real macOS .app

From project root:

./scripts/create_mac_app.sh

This generates ManeshTrader.app, which you can double-click like a normal app or move to /Applications.

Build a distributable installer DMG:

./scripts/create_installer_dmg.sh

Output: ManeshTrader-YYYYMMDD-HHMMSS.dmg in project root.

Share With Non-Technical Users (Self-Contained)

Build a standalone app that includes Python/runtime:

./scripts/build_standalone_app.sh

Then build DMG from that standalone app path:

APP_BUNDLE_PATH="dist-standalone/<timestamp>/dist/ManeshTrader.app" ./scripts/create_installer_dmg.sh

Tip: sign and notarize before sharing broadly, so macOS trust prompts are reduced.

4) First Session Walkthrough

  1. At app start, complete Profile Login:
    • Login profile name: type an existing profile, then click Login
    • PIN (if enabled): enter PIN for protected profiles
    • Remember me on this browser: keeps non-PIN profiles signed in across visits
    • Create profile name: type a new unique profile, then click Create Profile
    • Set PIN (optional, 4-6 digits): add lightweight profile protection
  2. After login, use sidebar Switch profile to change users.
  3. Note: profile names are case-insensitive for uniqueness (Matt and matt count as the same profile).
  4. Sidebar Profile section shows audit stamps for created time, last login, last settings update, and last symbol.
  5. Set Symbol (examples: AAPL, MSFT, BTC-USD, ETH-USD).
  6. Optional: choose Market Preset (Stocks Swing or Crypto Intraday) for one-click defaults.
  7. Optional: add symbols to Watchlist and use quick-select buttons.
  8. Set Timeframe (start with 1d to avoid noisy intraday data).
  9. Set Period (try 6mo initially).
  10. Keep Ignore potentially live last bar ON.
  11. Keep filters OFF for baseline:
  • Use previous body range (ignore wicks) OFF
  • Enable volume filter OFF
  • Hide market-closed gaps (stocks) ON
  1. Review top metrics:
  • Current Trend
  • Real Bullish Bars
  • Real Bearish Bars
  • Fake Bars
  1. Read What This Tool Means (Beginner Training):
  • Open Plain-English metric guide for quick definitions.
  • Review 1M / 3M / 6M / 1Y snapshot rows to see how this symbol behaved recently.
  • Use What this says to understand if conditions were trend-friendly or choppy.
  1. Read Trend Events for starts and reversals.
  2. Use Live Decision Guide to translate trend state into a practical bias/action/invalidation workflow.
  3. Keep Show past behavior examples ON while learning to review historical entry/exit outcomes.
  4. Set Display Timezone (US) to your preferred timezone (default is America/Chicago, CST/CDT).
  5. Choose Use 24-hour time ON for 13:00 style, or OFF for 1:00 PM style.

4.1) Advanced Features (Optional)

  • Advanced Signals:
    • Auto-run advanced panels (slower): keeps multi-timeframe/compare updating every rerun
    • Run advanced panels now: one-shot run to avoid UI hangs during normal editing
    • Show multi-timeframe confirmation (1h/4h/1d)
    • Regime filter (stand aside in choppy periods)
  • Training & Guidance:
    • Replay mode (hide future bars) + Replay bars shown
  • Monitoring:
    • Display Timezone (US): controls audit/event/training timestamp timezone (America/Chicago default)
    • Use 24-hour time: switches between 13:00 and 1:00 PM time styles
  • Compare Symbols:
    • enable panel and provide comma-separated symbols (AAPL, MSFT, NVDA)
  • Alerts:
    • enable bullish/bearish rule alerts
    • optional webhook URL for external delivery (Telegram/email automation via Zapier/Make/webhook adapters)
  • Backtest Controls:
    • slippage/fee bps
    • stop-loss/take-profit %
    • min/max hold bars

5) How To Read The Chart

  • Candle layer: full price action
  • Green triangle-up markers: real_bull
  • Red triangle-down markers: real_bear
  • Gray candles (if enabled): visually de-emphasized fake bars
  • Volume bars are colored by trend state
  • Optional training overlays:
    • blue circle: example long entry
    • orange diamond: example short entry
    • green X: example winning exit
    • red X: example loss/flat exit

6) Training Mode (New)

Training toggles are OFF by default.

Use these toggles in sidebar Training & Guidance:

  • Show live decision guide: summarizes current bias, signal status, and invalidation rule.
  • Show past behavior examples: shows historical hypothetical trades and outcomes.
  • Overlay example entries/exits on chart: draws example entry/exit markers on candles.
  • Focus chart on selected example: zooms chart around the clicked training row.
  • Max training examples: controls how many recent closed examples to include.

Example-trade method:

  • Enter on a confirmed trend-change bar close.
  • Exit on the opposite confirmed trend-change bar close.
  • Direction is LONG in bullish trend and SHORT in bearish trend.

6.1) Tutorial: Use This Like a Training Coach

Goal: learn what the model is signaling and what would have happened if you followed it.

Step A: Set up a clean training view

  1. In sidebar, choose a liquid symbol (AAPL or BTC-USD).
  2. Start with:
    • Timeframe = 1d (less noise)
    • Period = 6mo
    • Ignore potentially live last bar = ON
  3. Turn ON:
    • Show live decision guide
    • Show past behavior examples
    • Overlay example entries/exits on chart
    • Focus chart on selected example (optional but recommended while learning)
  4. Set Max training examples = 20.

Step B: Read current signal (what to do now)

  1. Look at Live Decision Guide.
  2. Use Bias as your directional filter:
    • Long Bias: only evaluate long ideas.
    • Short Bias: only evaluate short ideas.
    • Stand Aside / Neutral: wait for clearer confirmation.
  3. Read Signal Status:
    • Fresh Confirmation: a new active trend was confirmed on the latest closed bar.
    • No New Confirmation: no fresh reversal confirmation on the latest closed bar.
  4. Use Invalidation rule as the condition that would cancel your current bias.

Step C: Study historical behavior (what would have happened)

  1. Open Past Behavior Examples (Training).
  2. Review summary metrics:
    • Closed Examples
    • Wins / Losses
    • Example Win Rate
    • Avg P/L per Example
  3. Read the latest row first, then scan older examples.
  4. On chart, compare markers to price structure:
    • blue circle: long entry
    • orange diamond: short entry
    • green X: winning exit
    • red X: loss/flat exit
  5. Click any row in the examples table:
    • app highlights that exact trade path on chart
    • app shows a plain-English explanation of that row

Step D: Practice loop (recommended)

  1. Pick one symbol/timeframe.
  2. Hide the table briefly and decide what you would do from Live Decision Guide.
  3. Re-open table and compare your decision to recent example outcomes.
  4. Repeat across different regimes:
    • trending periods
    • choppy/sideways periods
  5. Keep notes on where the model performs best/worst.

Step E: Move from training to live monitoring

  1. Keep Show live decision guide ON.
  2. Keep Ignore potentially live last bar ON to reduce unfinished-bar noise.
  3. Enable Auto-refresh only when actively monitoring.
  4. Treat this as a decision-support layer, not an execution signal by itself.

7) Recommended Settings By Asset

Stocks (swing)

  • Timeframe: 1d
  • Period: 6mo or 1y
  • Max bars: 300-800

Crypto (shorter horizon)

  • Timeframe: 1h or 4h
  • Period: 1mo-6mo
  • Enable auto-refresh only when monitoring live

8) Optional Filters

Ignore Wicks

Use when long wicks create false breakouts; compares close to previous body only.

Volume Filter

Treats low-volume bars as fake:

  • Enable Enable volume filter
  • Start with:
    • Volume SMA window = 20
    • Min volume / SMA multiplier = 1.0

Hide Market-Closed Gaps (Stocks)

Compresses non-trading time on stock charts:

  • 1d: removes weekends and full missing days (for example exchange holidays with no bars)
  • intraday (1m..1h): removes weekends, full missing days, and overnight closed hours; x-axis labels show one date per trading day

Use OFF for 24/7 markets (for example many crypto workflows) when you want continuous time.

9) Exports

  • CSV: Download classified data (CSV)
  • PDF chart: Download chart (PDF)

If PDF fails, ensure kaleido is installed (already in requirements.txt).

10) Troubleshooting

App won’t start

./run.sh --setup-only
./run.sh

I see a blank/skeleton placeholder on refresh

  • A brief placeholder can appear while Streamlit initializes the page.
  • Wait a moment; this is expected loading behavior, not an app crash.

Port already in use

streamlit run app.py --server.port 8502

Bad symbol/data error

  • Verify ticker format (BTC-USD, not BTCUSD)
  • Use compatible Timeframe + Period

My settings changed unexpectedly

  • Confirm you are logged into your own profile.
  • Use sidebar Switch profile if needed.
  • Share profile-specific links by including ?profile=<your-name> in the app URL.
  • If you were inactive for more than 30 minutes, the app will require login again.

Watchlist or preset not applying as expected

  • Watchlist uses comma-separated symbols and deduplicates automatically.
  • Select a non-Custom preset and click Apply Preset to populate defaults.
  • After applying, you can still manually tweak any field.

Replay mode looks different than normal view

  • Replay mode intentionally truncates visible bars to simulate no-hindsight training.
  • Disable replay mode to return to full-history analysis.

Alert webhook errors

  • Confirm webhook URL accepts JSON POST.
  • For Telegram/email, route through an automation endpoint that supports incoming webhooks.

PIN login fails

  • Ensure the profile name is correct (name matching is case-insensitive).
  • PIN must be exactly what was set during profile creation (4-6 digits).

Why did auto-login not happen?

  • Remember me only auto-restores profiles without PIN.
  • PIN-protected profiles still require PIN on a fresh/expired session.

I still see some time gaps

  • For stocks, keep Hide market-closed gaps (stocks) ON.
  • Daily charts remove weekends + full no-data days; intraday removes weekends + full no-data days + closed hours.
  • Day-based periods (1d, 5d) backfill to target trading-day count when provider limits allow.
  • Half-days can still look visually compressed because they are partial sessions, not missing sessions.

Exports crash with timestamp errors

  • Pull latest project changes (export logic now handles named index columns)

11) Safety Notes

  • This app is analysis-only, no trade execution.
  • Backtest snapshot is diagnostic and simplistic.
  • Not financial advice.

12) Useful Commands

Setup only:

./run.sh --setup-only

Run tests:

make test

Run app:

make run