docs: fix score-dimension docstrings, CLI/collection naming drift, remove unmounted-backtest claim #86

Merged

gertjan merged 1 commit from docs/fix-drift into main

2026-07-14 18:20:42 +00:00

gertjan commented

2026-07-14 17:58:57 +00:00

Owner

Summary

Docs/comments-only drift cleanup — no functional changes. All items verified against current source before editing.

Stale composite-score dimension counts/weights (the code moved from 5/6 dimensions to the current 8-dimension scheme in src/analytics/scoring.py: momentum 25%, technical 15%, trend 15%, fundamental 12%, analyst 12%, sentiment 8%, stability 8%, volume 5%, with regime-shifted presets). Fixed everywhere the stale numbers were still quoted:
- src/api/routes/analytics.py — module docstring (top of file) and the /analytics/scores endpoint docstring.
- src/cli/client.py — analytics scores command docstring, and the hardcoded weight labels in _print_score_detail.
- README.md — the "Composite asset scoring" feature bullet and the scores_snapshot row in the MongoDB collections table.
- docs/schema.md — the scores_snapshot field table (was missing fundamental_score/analyst_score/sentiment_score entirely and had the old weights on the rest).
- All rewritten docstrings/tables now point at DimensionWeights / WEIGHT_PRESETS in src/analytics/scoring.py as the source of truth, so this shouldn't re-drift silently again.
README.md CLI drift: ops check-timeseries → analytics check-timeseries (the command is registered under analytics_app, see src/cli/commands.py:1092).
REFERENCE.md fictional CLI recipe: removed bodega backtest run AAPL,MSFT --strategy sma-cross --fast 10 --slow 30 — grepped src/cli/commands.py and src/cli/client.py; there is no backtest CLI command anywhere. Backtesting is API-only via POST /analytics/backtest, which REFERENCE.md already documents correctly elsewhere. Replaced the line with a one-line pointer instead of a fake recipe.
Correlation/regime collection-naming drift (checked, no change needed): grepped README.md, REFERENCE.md, DEVELOPMENT.md, CLAUDE.md, AGENTS.md, docs/*.md, TASK_HEALTH_MONITORING.md for correlation_peers/correlation_clusters/correlation_leadlag or a regime collection. Found no such references — current docs either don't mention these collections at all or correctly describe the single correlation_snapshot (doc_type discriminator: peers/cluster/lead_lag, per src/database/repositories/correlation.py) and regime_snapshot (per src/database/repositories/regime.py). No edit made for this item since no drift exists.

Investigation: `src/api/routes/backtest.py` (not mounted) — report only, no code change

Per the task, I did not mount the router and did not delete the file. History:

src/api/routes/backtest.py was created in commit 581cd9d ("feat(backtest): add vectorised backtesting engine with SMA/RSI strategies (F4)", 2026-03-13). That same commit also added a full POST /analytics/backtest endpoint directly inline in src/api/routes/analytics.py (103 lines).
git log --follow on backtest.py shows only 3 touching commits total (creation, a docs-pass commit 5754a6e, and a lint-fix commit f5b16b0) — it was never functionally changed after creation.
git log -p -- src/api/main.py across all of history has zero occurrences of backtest in any diff hunk (the one incidental match is an unrelated comment about "simulation/backtesting system"). So backtest.py's APIRouter (prefix="/analytics", its own POST /backtest) was never mounted, at any point — it wasn't unmounted later; it simply was dead code from the moment it was created.
Comparing the two implementations: analytics.py's inline version (the live one, since analytics.router is included in main.py) is the more mature implementation — proper parse_date() validation, structured BacktestResponse model, consistent error handling. backtest.py's standalone version is a more primitive first draft (raw datetime.fromisoformat, untyped dict[str, Any] return, no date validation).
My read: this looks like the author started implementing the endpoint in a dedicated routes/backtest.py file, then decided partway through the same commit to inline it into analytics.py instead (likely to reuse analytics.py's existing dependencies/helpers), and simply forgot to delete the now-orphaned draft file. It's safe to delete — the owner should decide whether to do that or keep it as reference/for a future split.

Verification

Run against the rebased branch tip:

ruff check src/ — all checks passed
mypy src/ — no issues found in 207 source files
pytest -m "not integration" — 1067 passed, 27 deselected

Test plan

ruff check src/
mypy src/
pytest -m "not integration"
Manual grep verification of every claim against current source (src/analytics/scoring.py, src/cli/commands.py, src/api/main.py, src/database/repositories/correlation.py, src/database/repositories/regime.py) before editing

🤖 Generated with Claude Code

## Summary Docs/comments-only drift cleanup — no functional changes. All items verified against current source before editing. - **Stale composite-score dimension counts/weights** (the code moved from 5/6 dimensions to the current 8-dimension scheme in `src/analytics/scoring.py`: momentum 25%, technical 15%, trend 15%, fundamental 12%, analyst 12%, sentiment 8%, stability 8%, volume 5%, with regime-shifted presets). Fixed everywhere the stale numbers were still quoted: - `src/api/routes/analytics.py` — module docstring (top of file) and the `/analytics/scores` endpoint docstring. - `src/cli/client.py` — `analytics scores` command docstring, and the hardcoded weight labels in `_print_score_detail`. - `README.md` — the "Composite asset scoring" feature bullet and the `scores_snapshot` row in the MongoDB collections table. - `docs/schema.md` — the `scores_snapshot` field table (was missing `fundamental_score`/`analyst_score`/`sentiment_score` entirely and had the old weights on the rest). - All rewritten docstrings/tables now point at `DimensionWeights` / `WEIGHT_PRESETS` in `src/analytics/scoring.py` as the source of truth, so this shouldn't re-drift silently again. - **README.md CLI drift**: `ops check-timeseries` → `analytics check-timeseries` (the command is registered under `analytics_app`, see `src/cli/commands.py:1092`). - **REFERENCE.md fictional CLI recipe**: removed `bodega backtest run AAPL,MSFT --strategy sma-cross --fast 10 --slow 30` — grepped `src/cli/commands.py` and `src/cli/client.py`; there is no `backtest` CLI command anywhere. Backtesting is API-only via `POST /analytics/backtest`, which REFERENCE.md already documents correctly elsewhere. Replaced the line with a one-line pointer instead of a fake recipe. - **Correlation/regime collection-naming drift (checked, no change needed)**: grepped README.md, REFERENCE.md, DEVELOPMENT.md, CLAUDE.md, AGENTS.md, docs/*.md, TASK_HEALTH_MONITORING.md for `correlation_peers`/`correlation_clusters`/`correlation_leadlag` or a `regime` collection. Found no such references — current docs either don't mention these collections at all or correctly describe the single `correlation_snapshot` (doc_type discriminator: peers/cluster/lead_lag, per `src/database/repositories/correlation.py`) and `regime_snapshot` (per `src/database/repositories/regime.py`). No edit made for this item since no drift exists. ## Investigation: `src/api/routes/backtest.py` (not mounted) — report only, no code change Per the task, I did **not** mount the router and did **not** delete the file. History: - `src/api/routes/backtest.py` was created in commit `581cd9d` ("feat(backtest): add vectorised backtesting engine with SMA/RSI strategies (F4)", 2026-03-13). That **same commit** also added a full `POST /analytics/backtest` endpoint directly inline in `src/api/routes/analytics.py` (103 lines). - `git log --follow` on `backtest.py` shows only 3 touching commits total (creation, a docs-pass commit `5754a6e`, and a lint-fix commit `f5b16b0`) — it was never functionally changed after creation. - `git log -p -- src/api/main.py` across all of history has **zero** occurrences of `backtest` in any diff hunk (the one incidental match is an unrelated comment about "simulation/backtesting system"). So `backtest.py`'s `APIRouter` (`prefix="/analytics"`, its own `POST /backtest`) was **never mounted, at any point** — it wasn't unmounted later; it simply was dead code from the moment it was created. - Comparing the two implementations: `analytics.py`'s inline version (the live one, since `analytics.router` **is** included in `main.py`) is the more mature implementation — proper `parse_date()` validation, structured `BacktestResponse` model, consistent error handling. `backtest.py`'s standalone version is a more primitive first draft (raw `datetime.fromisoformat`, untyped `dict[str, Any]` return, no date validation). - **My read**: this looks like the author started implementing the endpoint in a dedicated `routes/backtest.py` file, then decided partway through the same commit to inline it into `analytics.py` instead (likely to reuse `analytics.py`'s existing dependencies/helpers), and simply forgot to delete the now-orphaned draft file. It's safe to delete — the owner should decide whether to do that or keep it as reference/for a future split. ## Verification Run against the rebased branch tip: - `ruff check src/` — all checks passed - `mypy src/` — no issues found in 207 source files - `pytest -m "not integration"` — 1067 passed, 27 deselected ## Test plan - [x] `ruff check src/` - [x] `mypy src/` - [x] `pytest -m "not integration"` - [x] Manual grep verification of every claim against current source (`src/analytics/scoring.py`, `src/cli/commands.py`, `src/api/main.py`, `src/database/repositories/correlation.py`, `src/database/repositories/regime.py`) before editing 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gertjan added 1 commit

2026-07-14 17:58:57 +00:00

docs: fix score-dimension docstrings, CLI/collection naming drift, remove unmounted-backtest claim

Deploy / check (pull_request) Successful in 3m23s

Details

Deploy / deploy (pull_request) Has been skipped

Details

c5ad0bf3c0

- Update stale 5/6-dimension composite-score docstrings (analytics.py routes,
  cli/client.py) to match the authoritative 8-dimension scheme in
  src/analytics/scoring.py (momentum 25%, technical 15%, trend 15%,
  fundamental 12%, analyst 12%, sentiment 8%, stability 8%, volume 5%),
  pointing at scoring.py as the source of truth to prevent re-drift.
- README.md: correct `ops check-timeseries` to `analytics check-timeseries`
  (actual CLI group per src/cli/commands.py:1092).
- REFERENCE.md: remove the fictional `bodega backtest run` CLI recipe — no
  such CLI command exists; backtesting is API-only via POST /analytics/backtest.
- docs/schema.md: fix scores_snapshot field table to the current 8-field
  AssetScore model and weights.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

gertjan force-pushed docs/fix-drift from c5ad0bf3c0

Deploy / check (pull_request) Successful in 3m23s

Details

Deploy / deploy (pull_request) Has been skipped

Details

to e48301974f

Deploy / check (pull_request) Successful in 3m19s

Details

Deploy / deploy (pull_request) Has been skipped

Details

2026-07-14 18:17:19 +00:00

Compare