Skip to content

Sync documentation to current codebase state (v0.2.2) #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Codex-Crusader merged 1 commit into from
Apr 12, 2026
Merged

Sync documentation to current codebase state (v0.2.2) #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Docs/code_flow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ flowchart TD

## 2. Background Full-Market Scan

`_run_background_scan` delegates entirely to `app.scan.run_scan()`. News is fetched once and reused across all 24 assets processed sequentially. Per-asset snapshots are saved via `analyse_asset(save=True)`.
`_run_background_scan` delegates entirely to `app.scan.run_scan()`. News is fetched once and reused across all 24 assets. A `price_cache` (`{ticker: change_1d}`) is pre-built via `fetch_all_metrics_parallel` before the loop, eliminating redundant yfinance calls during context analysis. Each asset is analysed with `with_market_ctx=True` and `save=True`.

```mermaid
flowchart TD
Expand All @@ -57,7 +57,7 @@ flowchart TD

FETCHNEWS --> LOOPSTART{Next asset in\nTRACKED_ASSETS?}

LOOPSTART -->|More assets| ANALYSE[analyse_asset\nasset_name ticker category articles\nwith_market_ctx=False\nsave=True]
LOOPSTART -->|More assets| ANALYSE[analyse_asset\nasset_name ticker category articles\nwith_market_ctx=True\nsave=True\nprice_cache=price_cache]
LOOPSTART -->|All done| SUMMARY

ANALYSE --> ASUCCESS{Success?}
Expand Down
21 changes: 15 additions & 6 deletions Docs/variable_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@ Returns `dict`:

---

#### `analyse_asset(asset_name, ticker, category, articles, with_market_ctx, save)`
#### `analyse_asset(asset_name, ticker, category, articles, with_market_ctx, save, price_cache)`

| Parameter | Type | Default | Description |
|---|---|---|---|
Expand All @@ -311,6 +311,7 @@ Returns `dict`:
| `articles` | `list[dict]` | — | Pre-fetched article pool |
| `with_market_ctx` | `bool` | `False` | Whether to run `analyse_market_context` |
| `save` | `bool` | `False` | Whether to persist a snapshot via `save_snapshot`. Only the batch scan pipeline passes `True`. |
| `price_cache` | `Optional[dict[str, float]]` | `None` | Pre-built `{ticker: change_1d}` map. Passed to `analyse_market_context` so peer/benchmark lookups are served from memory instead of making extra yfinance calls. Has no effect when `with_market_ctx=False`. |

Returns `dict`:

Expand All @@ -326,6 +327,7 @@ Returns `dict`:
| `signal` | `dict` | Output of `compute_signal_score` |
| `explanation` | `dict` | Output of `build_explanation` |
| `historical_features` | `dict` | Output of `storage.get_historical_features` |
| `error` | `Optional[dict]` | Error payload dict if price fetch failed, otherwise `None`. Contains `type`, `exception`, `stage`, `message` keys. |

---

Expand All @@ -341,7 +343,7 @@ Fetches price metrics and momentum for every tracked asset in parallel using `PR
{category: {asset_name: {"metrics": <price_metrics_dict>, "momentum": <momentum_dict>}}}
```

Available for external use but not called by the dashboard directly. The dashboard heatmap and category overview use `cached_scan_summary()` in `dashboard/data.py` instead.
Called by `app/scan.py` during the batch pipeline to pre-build the `price_cache` before the per-asset loop (eliminating ~50–80 redundant yfinance calls). Also available for external use. The dashboard heatmap and category overview use `cached_scan_summary()` in `dashboard/data.py` rather than calling this directly.

---

Expand Down Expand Up @@ -509,8 +511,11 @@ These functions live in `dashboard/components.py`.
| `scan_time` | `str` | ISO datetime string of scan start |
| `total` | `int` | Total number of assets processed |
| `succeeded` | `int` | Number of assets that completed without error |
| `errors` | `list[dict]` | List of error dicts each with `asset`, `category`, `error` keys |
| `errors` | `list[dict]` | List of error dicts each with `asset`, `category`, `type`, `stage`, `message` keys |
| `results` | `dict[str, dict[str, dict]]` | Nested `{category: {asset_name: entry_dict}}` |
| `top_movers` | `dict` | Pre-computed dict with `gainers` and `losers` lists (top 5 each by 24h change) |
| `heatmap` | `dict` | Pre-computed heatmap matrix with `z`, `text`, `categories`, `max_assets` keys for the Plotly heatmap |
| `category_rows` | `dict` | Pre-computed per-category row data: `{category: {"rows": list, "missing": list}}` |

### Entry Dict Within `results`

Expand All @@ -522,14 +527,18 @@ These functions live in `dashboard/components.py`.
| `price` | `Optional[float]` | Latest close price |
| `change_1d` | `Optional[float]` | 1-day percentage change |
| `change_7d` | `Optional[float]` | 7-day percentage change |
| `change_30d` | `Optional[float]` | 30-day percentage change |
| `volatility` | `Optional[float]` | Daily return std deviation * 100 |
| `trend` | `Optional[str]` | Trend classification |
| `rsi` | `Optional[float]` | 14-period RSI |
| `roc_10d` | `Optional[float]` | 10-day ROC |
| `trend_strength` | `Optional[float]` | MA divergence percentage |
| `momentum_accel` | `Optional[float]` | ROC acceleration |
| `confidence` | `Optional[str]` | Explanation confidence level |
| `verdict` | `str` | One-line summary string |
| `top_movers` | `dict` | Pre-computed dict with `gainers` and `losers` lists (top 5 each by 24h change) |
| `heatmap` | `dict` | Pre-computed heatmap matrix with `z`, `text`, `categories`, `max_assets` keys for the Plotly heatmap |
| `category_rows` | `dict` | Pre-computed per-category row data for the category overview table: `{category: {"rows": list, "missing": list}}` |
| `is_market_wide` | `bool` | True if the benchmark moved > 0.5% in the same direction |
| `is_sector_wide` | `bool` | True if >= 60% of sector peers moved in the same direction |
| `error` | `Optional[dict]` | Error payload if price fetch failed, otherwise absent |

### `load_last_scan_summary()` Return Structure

Expand Down
Loading