Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>
This commit is contained in:
parent
ccb085f7f0
commit
ae787ca060
@ -14,6 +14,7 @@ A Python web app wrapped by a native macOS shell.
|
||||
- `web/src/web_core/`: strategy/data/chart/export modules
|
||||
- `web/src/requirements.txt`: Python dependencies
|
||||
- `web/src/ONBOARDING.md`: in-app onboarding guide content
|
||||
- `web/src/PRD.md`: web product rules and behavior spec
|
||||
|
||||
## macOS Shell
|
||||
- Project location: `mac/src/` (`*.xcodeproj` auto-discovered by scripts)
|
||||
|
||||
125
web/src/PRD.md
Normal file
125
web/src/PRD.md
Normal file
@ -0,0 +1,125 @@
|
||||
# Web PRD (Source of Truth)
|
||||
|
||||
## 1. Scope
|
||||
This document defines the product behavior for the Streamlit web app in `web/src/`.
|
||||
|
||||
This PRD is intentionally web-only:
|
||||
- Data fetch and analysis logic
|
||||
- Classification/trend rules
|
||||
- Filters, chart behavior, exports, and persisted settings
|
||||
|
||||
Out of scope:
|
||||
- macOS shell/wrapper architecture and packaging
|
||||
|
||||
## 2. Product Goal
|
||||
Provide an analysis-only charting tool that classifies OHLC bars as real/fake, tracks trend state using only real bars, and exposes clear visual + exportable outputs.
|
||||
|
||||
## 3. Inputs and Data Pipeline
|
||||
1. User configures:
|
||||
- `symbol`
|
||||
- `interval`
|
||||
- `period`
|
||||
- `max_bars`
|
||||
- filter/toggle settings
|
||||
2. App fetches OHLCV via Yahoo Finance (`yfinance`).
|
||||
3. Optional last-bar drop (live-bar guard) for intraday intervals.
|
||||
4. Bars are classified (`real_bull`, `real_bear`, `fake`, `unclassified` for first bar).
|
||||
5. Trend state is derived from classification sequence.
|
||||
6. UI renders metrics, chart, events, and export artifacts.
|
||||
|
||||
## 4. Settings Contract
|
||||
Persisted settings path:
|
||||
- Primary: `~/.web_local_shell/settings.json`
|
||||
- Legacy fallback read: `~/.manesh_trader/settings.json`
|
||||
|
||||
Normalization constraints:
|
||||
- `symbol`: uppercase, non-empty fallback `AAPL`
|
||||
- `interval`: must be one of `INTERVAL_OPTIONS`, fallback `1d`
|
||||
- `period`: must be one of `PERIOD_OPTIONS`, fallback `6mo`
|
||||
- `max_bars`: `[20, 5000]`, fallback `500`
|
||||
- `volume_sma_window`: `[2, 100]`, fallback `20`
|
||||
- `volume_multiplier`: `[0.1, 3.0]`, rounded to 0.1, fallback `1.0`
|
||||
- `refresh_sec`: `[10, 600]`, fallback `60`
|
||||
- booleans normalized from common truthy/falsy strings and numbers
|
||||
|
||||
## 5. Classification Rules
|
||||
For each bar `i` (starting at index 1):
|
||||
- Reference prior bar `i-1`.
|
||||
- If `use_body_range = false`:
|
||||
- `prev_high = prev.High`
|
||||
- `prev_low = prev.Low`
|
||||
- If `use_body_range = true`:
|
||||
- `prev_high = max(prev.Open, prev.Close)`
|
||||
- `prev_low = min(prev.Open, prev.Close)`
|
||||
|
||||
Volume filter:
|
||||
- If enabled, `volume_ok = Volume >= SMA(Volume, volume_sma_window) * volume_multiplier`
|
||||
- If `volume_ok` is false, classification is `fake` regardless of price break.
|
||||
|
||||
Price logic (when volume is OK):
|
||||
- `Close > prev_high` -> `real_bull`
|
||||
- `Close < prev_low` -> `real_bear`
|
||||
- otherwise -> `fake`
|
||||
|
||||
First bar is always `unclassified`.
|
||||
|
||||
## 6. Trend-State Rules
|
||||
Trend states:
|
||||
- `No Active Trend`
|
||||
- `Bullish Trend Active`
|
||||
- `Bearish Trend Active`
|
||||
|
||||
State machine:
|
||||
- From neutral:
|
||||
- 2 consecutive `real_bull` -> bullish trend started
|
||||
- 2 consecutive `real_bear` -> bearish trend started
|
||||
- From bullish:
|
||||
- 2 consecutive `real_bear` -> bearish reversal confirmed
|
||||
- From bearish:
|
||||
- 2 consecutive `real_bull` -> bullish reversal confirmed
|
||||
|
||||
Important:
|
||||
- `fake` bars do not increment opposite-run counters enough to reverse trend.
|
||||
|
||||
## 7. Chart and Visualization Behavior
|
||||
- Main candlestick chart with bullish/bearish markers:
|
||||
- `real_bull`: green triangle-up
|
||||
- `real_bear`: red triangle-down
|
||||
- Optional fake-bar de-emphasis via gray candle layer (`gray_fake`).
|
||||
- Volume subplot colored by trend state.
|
||||
|
||||
Gap handling (`hide_market_closed_gaps`):
|
||||
- Always removes weekend gaps (`sat` -> `mon`).
|
||||
- For intraday intervals, also removes inferred overnight hours using session bounds.
|
||||
- For daily interval, weekend break removal is applied.
|
||||
|
||||
## 8. Help and Onboarding Behavior
|
||||
- Web-only fallback help entry exists in sidebar:
|
||||
- `Help / Quick Start`
|
||||
- Content source: `web/src/ONBOARDING.md`
|
||||
- Help appears in a dialog.
|
||||
|
||||
## 9. Outputs
|
||||
- Metrics:
|
||||
- current trend
|
||||
- real bullish count
|
||||
- real bearish count
|
||||
- fake count
|
||||
- Trend events table (latest events)
|
||||
- Backtest snapshot:
|
||||
- signal at trend-change rows to active bull/bear states
|
||||
- next-bar close determines win/loss
|
||||
- Exports:
|
||||
- CSV always available
|
||||
- PDF via Plotly image export (requires Kaleido runtime)
|
||||
|
||||
## 10. Validation Expectations
|
||||
Code-level checks:
|
||||
- `python -m py_compile web/src/app.py`
|
||||
- `PYTHONPATH=web/src pytest -q web/src/tests`
|
||||
|
||||
Behavior checks:
|
||||
- No crash on missing/invalid persisted settings
|
||||
- Symbol/interval/period invalid combinations show actionable data error
|
||||
- Trend logic matches two-consecutive-real-bars contract
|
||||
- Exports include normalized timestamp column
|
||||
Loading…
Reference in New Issue
Block a user