Skip to content

feat(stocks): stocks rotation, a relative rotation graph against IHSG - #127

Merged
fzn0x merged 3 commits into
mainfrom
feat/stocks-rotation
Nov 13, 2026
Merged

fzn0x merged 3 commits into
mainfrom
feat/stocks-rotation

Conversation

@fzn0x

@fzn0x fzn0x commented Nov 13, 2026

Copy link
Copy Markdown
Owner

Closes #99. Scope and decisions are on the issue.

What it does

idx stocks rotation SYMBOLS (alias rrg) and the MCP tool idx_rotation place each ticker on a relative rotation graph against a benchmark, IHSG (^JKSE) by default: RS-Ratio (is it beating the benchmark?), RS-Momentum (is that getting stronger?), the quadrant (leading, weakening, lagging, improving), the change over the tail and the tail itself. New schema idx.rotation.v1.

Relative rotation vs ^JKSE (IDX COMPOSITE) · weekly, window 14, tail 10 · as of 2026-11-04
Open approximation of the JdK RS-Ratio and RS-Momentum; values differ from StockCharts and Optuma.
│ Symbol ┆ Quadrant  ┆ RS-Ratio ┆ RS-Momentum ┆ Ratio chg ┆ Momentum chg ┆ As of      ┆ Weeks │
│ BBCA   ┆ leading   ┆   100.63 ┆      100.63 ┆     +0.53 ┆        +0.09 ┆ 2026-11-04 ┆    53 │
│ TLKM   ┆ lagging   ┆    99.33 ┆       99.50 ┆     +0.46 ┆        -1.08 ┆ 2026-11-04 ┆    53 │
│ GIAA   ┆ improving ┆    98.86 ┆      100.06 ┆     -1.79 ┆        +0.08 ┆ 2026-11-04 ┆    53 │
│ ITMG   ┆ weakening ┆   101.76 ┆       98.66 ┆     +1.16 ┆        -1.11 ┆ 2026-11-04 ┆    53 │
│ RS-Momentum >= 100 ┆ improving: GIAA ┆ leading: BBCA   │
│ RS-Momentum < 100  ┆ lagging: TLKM   ┆ weakening: ITMG │
│                    ┆ RS-Ratio < 100  ┆ RS-Ratio >= 100 │

(the recorded fixtures; live data runs to today)

Method: an open approximation, labelled as one

The JdK formulas are proprietary. On the dates a stock and the benchmark share, resampled to each week's last session by default:

  • RS = 100 x close / benchmark close
  • RS-Ratio = 100 + (RS - mean) / sd over the window
  • RS-Momentum = 100 + the same z-score of RS-Ratio's rate of change

Sample sd, two decimals, 100 counts as the upper and right side. method.approximation: true and method.formula in the JSON, the table header, --help, the MCP description and the README all say it approximates JdK.

Decisions (as recommended on #99)

  • Weekly bars, window 14, tail 10; --window (3 to 100) and --tail (1 to 52) are flags; --interval 1d for sessions. The current week counts with its latest session.
  • Symbols: the user's own (or - from stdin). No bundled LQ45 list (it changes twice a year); ^JKLQ45 and ^JKII work as symbols or benchmark (5y history checked on Yahoo).
  • History: five years of daily candles, the same request as stocks returns, so the two share the cache.
  • Web: CLI and MCP only for now (no scatter chart on the page yet); the terminal routes stocks rotation, rotation and rrg to its notice. Tools go from 47 to 48.
  • No sector graph: Yahoo has no history for the IDX-IC sector indices (IDXFINANCE.JK answers a 1d/5d snapshot only).

A short history (a new listing) or a symbol that moved exactly with the benchmark gives null values with a warning, never a fill. A warning names symbols whose newest close waits for ^JKSE's bar (often a session late).

Tests

  • Unit (7): weekly resampling across the new year, warm-up of 2 x window bars, no spread no point, a short history, quadrant edges, one point computed by hand, and the recorded charts in all four quadrants. The fixture values match an independent computation of the same formulas.
  • CLI (3): JSON values and tails, the table and its quadrants, --interval 1d --window 20 --tail 5 in JSONL, a missing symbol as a warning, a missing benchmark (exit 5), bad flags (exit 2), idx schema rotation.
  • MCP: idx_rotation from the seeded cache, and bad interval and window as usage errors; 48 tools.
  • Web: routing, tools list, landing tables.
  • Gates: fmt, clippy, cargo test 766 lib, 75 cli, 2 mcp; web 327; npm 6; worker check. Each of the three commits builds and passes on its own.
  • Live: idx stocks rotation BBCA BBRI TLKM GOTO ASII and idx stocks rrg BBCA ^JKLQ45 against Yahoo, as of 2026-11-13. scripts/smoke.sh gains the same lines.

Docs

README (a Relative rotation section, the commands table, MCP list, schema list, IDX_EXCHANGE, stdin), docs/json-output.md, docs/mcp.md, docs/agent-guide.md, AGENTS.md.

analysis::rotation computes a relative rotation graph from daily closes:
RS = 100 x close / benchmark close on shared dates, RS-Ratio = 100 + the
z-score of RS over a rolling window, RS-Momentum = 100 + the z-score of
RS-Ratio's rate of change (sample sd), resampled to each week's last
session by default. The JdK formulas are proprietary, so the model
carries method.approximation = true and the formula in words.

model::rotation holds the JSON contract: Rotation, RotationRow (latest
point, change over the tail, the tail), RotationPoint, Quadrant (leading,
weakening, lagging, improving; 100 counts as the upper and right side),
RotationInterval (1wk | 1d) and RotationMethod. A flat RS (a symbol that
moved with its benchmark) or a short history gives no point, never a fill.

Tested on synthetic series (warm-up of 2 x window bars, ISO weeks across
the new year, a point computed by hand) and on the recorded one-year
charts: as of 2026-11-04, BBCA leading, TLKM lagging, GIAA improving, ITMG
weakening, matching an independent computation of the same formulas.
idx stocks rotation SYMBOLS [--benchmark ^JKSE] [--interval 1wk|1d]
[--window 14] [--tail 10] (alias rrg), and the MCP tool idx_rotation with
the same arguments, return idx.rotation.v1: each symbol's RS-Ratio,
RS-Momentum, quadrant, change over the tail and the tail itself.

service::rotation reads five years of daily candles, the history `stocks
returns` reads, so the two share the cache; at most 8 symbols at a time.
The benchmark must be readable; a symbol that fails is a warning, one with
a short history keeps its row with null values and a warning, and a
warning names the symbols whose newest close waits for ^JKSE's bar (it
often arrives a session late). The table lists the rows, then the four
quadrants laid out as the graph draws them; -o jsonl prints one line per
symbol, so `idx stocks quote -` reads them back.

The web terminal does not draw a scatter chart yet: idx_rotation is CLI
and MCP only there (tools.js, the landing tables, 48 tools), and `stocks
rotation`, `rotation` and `rrg` reach its notice (route.js, which gains the
MCP-only lookup under stocks). docs/mcp.md, docs/json-output.md and
scripts/smoke.sh follow.
README gains a Relative rotation section (what the axes and quadrants
mean, the formulas, why it is an approximation of the JdK RRG, defaults,
history needed, no sector graph yet, CLI and MCP only) and the command in
the tables and lists; the agent guide says to quote it as an
approximation; AGENTS.md lists the new modules and subcommand.
@fzn0x fzn0x added this to the 0.8.4 milestone Nov 13, 2026
@fzn0x fzn0x added enhancement New feature or request stocks stocks command group cli command line surface, flags, output formats mcp MCP server and tools labels Nov 13, 2026
@fzn0x fzn0x mentioned this pull request Nov 13, 2026
5 of 18 tasks
@fzn0x
fzn0x merged commit 1d8c95f into main Nov 13, 2026
6 checks passed
@fzn0x
fzn0x deleted the feat/stocks-rotation branch November 13, 2026 19:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cli command line surface, flags, output formats enhancement New feature or request mcp MCP server and tools stocks stocks command group

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Relative Rotation Graph

1 participant