You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: cli/README.md
+39-7Lines changed: 39 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -104,7 +104,8 @@ Every invocation is **one mode** (a primary flag) + a positional strategy/entry
104
104
|**Candle Dump**|`--dump`| Fetch & save raw OHLCV candles to a file |
105
105
|**PnL Debug**|`--pnldebug`| Simulate per-minute PnL for a given entry price & direction |
106
106
|**Broker Debug**|`--brokerdebug`| Fire a single broker commit against the live adapter |
107
-
|**Simulator**|`--simulator`| Sweep exit/entry parameters over a crowd-ideas feed, train an author whitelist |
107
+
|**Simulator**|`--simulator`| Feasibility probe over a crowd-ideas feed: is there a profitable corridor at all |
108
+
|**Tune**|`--tune`| Walk-forward parameter search over a crowd-ideas feed: train on the head, one frozen shot on the tail |
108
109
|**Flush**|`--flush`| Delete report/log/markdown/agent folders from a strategy dump dir |
109
110
|**Init**|`--init`| Scaffold a new project |
110
111
|**Docker**|`--docker`| Scaffold a self-contained Docker workspace |
@@ -267,12 +268,12 @@ The same shape works for `--live --entry` / `--paper --entry` (call `Live.backgr
267
268
268
269
## 🛠️ Tooling modes
269
270
270
-
Six utilities that don't run a strategy. They share one convention, explained once here and referenced below.
271
+
Utilities that don't run a strategy. They share one convention, explained once here and referenced below.
271
272
272
273
> **The `<mode>.module` convention.** By default the CLI auto-registers CCXT Binance. To use a different exchange (custom API keys, rate limits, a non-spot market), drop a `modules/<mode>.module.ts` that calls `addExchangeSchema` from `backtest-kit`. The CLI loads it automatically before running, trying `.ts`/`.mjs`/`.cjs`; it's searched **next to the target file first, then in the project root**. `.env` is loaded root-first then the target-file dir (override), so API keys stay out of code.
// modules/pine.module.ts (same shape for editor/dump/pnldebug.module; brokerdebug registers a Broker instead)
@@ -452,19 +453,19 @@ The CLI loads `./modules/brokerdebug.module`, fetches the last candle for `--sym
452
453
453
454
### 🎛️ Simulator (`--simulator`)
454
455
455
-
Sweep exit/entry parameters over a feed of crowd trading ideas using the `Simulator` entity — one candle pass per idea, a full parameter gridevaluated arithmetically, an author whitelist trained with default-ban semantics. Prints a Markdown report with four ranking winners (time-based Sharpe, Sortino, PnL, recovery factor) and the production whitelist.
456
+
A **feasibility probe** over a feed of crowd trading ideas: does the feed contain a profitable corridor at all, or is there nothing to search? The probe deliberately does NOT try to earn — the profit-harvesting machinery is off (no profit lock, inert trailing take, no weighted consensus), and a fast **48-point grid** of hard stop × hold × ban rule is evaluated from one candle pass per idea. The parameter search itself is `--tune`'s job. Prints a Markdown report with the corridor share, four ranking winners as evidence, and the whitelist of the sharpe winner's ban rule.
**Positional (required):** path to an ideas `.jsonl` file — one idea per line, exact shape `{ "id": number, "ts": number, "symbol": string, "direction": "LONG"|"SHORT"|"NEUTRAL", "author": string }`. The file is validated **before any work starts** — the first line that does not match the structure aborts the run with an error naming the line and the field. Ideas of other symbols are filtered out by the engine, so one shared feed serves any `--symbol`.
476
477
477
-
Under the hood: 5-day candle horizon per idea (lazy chunked fetch through the exchange, persist cache first), flood dedupe (one idea per author per direction per 8h), author ban thresholds swept as grid axes (unproven author = banned by default), production slot semantics, time-based Sharpe/Sortino over daily equity buckets. With `--verbose` every lifecycle callback (`onIdeas`, `onProfiles`, `onAuthorsTrained`, `onGridPoint`, `onRanking`, `onDone`) is logged to the console as it fires, so long runs show progress. Exchange via `simulator.module` (see convention above).
478
+
Under the hood: 5-day candle horizon per idea (lazy chunked fetch through the exchange, persist cache first), flood dedupe (one idea per author per direction per 8h), default-ban author filter (track/hit-rate thresholds swept — unproven author = banned), production slot semantics, time-based Sharpe/Sortino over daily equity buckets. A position is entered on a proven author's idea and exits by time or catastrophe stop, nothing else — if even this primitive corridor is unprofitable on its own training range, the feed carries no extractable signal. With `--verbose` every lifecycle callback (`onIdeas`, `onProfiles`, `onAuthorsTrained`, `onGridPoint`, `onRanking`, `onDone`) is logged to the console as it fires, so long runs show progress. Exchange via `simulator.module` (see convention above).
479
+
480
+
</details>
481
+
482
+
### 🔧 Tune (`--tune`)
483
+
484
+
The **parameter search** counterpart of the `--simulator` probe: a walk-forward sweep of the full grid with the profit-harvesting machinery ON — profit lock, trailing take, weighted consensus, Wilson-bound ban, both author-hit metrics (close/reach). Honesty is structural: training sees only the head of the feed (`--split` of its time range, default 70%), then the sharpe winner is frozen — point and raw author track record — and fired **exactly once** on the tail via `Simulator.test`. Nothing is trained on the tail; authors unseen in training are banned by default.
# → train winners + one out-of-sample shot; add --json / --markdown to save into ./dump/
489
+
```
490
+
491
+
<details>
492
+
<summary>Tune flags, input format & behavior</summary>
493
+
494
+
| Flag | Type | Description |
495
+
|------|------|-------------|
496
+
|`--tune`| boolean | Enable the walk-forward parameter search |
497
+
|`--symbol`| string | Trading pair to tune (default `"BTCUSDT"`) |
498
+
|`--exchange`| string | Exchange (default: first registered, falls back to CCXT Binance) |
499
+
|`--split`| string | Train share of the feed time range, 0..1 (default `0.7`) |
500
+
|`--output`| string | Output base name (default `tune_{SYMBOL}_{TIMESTAMP}`) |
501
+
|`--json`| boolean | Save `{ trainSplit, train, test }` to `./dump/<output>.json`|
502
+
|`--markdown`| boolean | Save the walk-forward report to `./dump/<output>.md`|
503
+
|`--verbose`| boolean | Log simulator lifecycle callbacks to the console |
504
+
505
+
**Positional (required):** path to an ideas `.jsonl` file — same shape and validation as `--simulator`.
506
+
507
+
The report carries the train winners of all four ranking criteria (full point labels including lock, Wilson bound and the author-hit metric), the out-of-sample result of the frozen sharpe winner with its trade list, and the **frozen author track record** — the raw `author/ideas/hits` numbers to hardcode for production `Simulator.test`: banned flags and vote weights are re-derived from them under the frozen point's rule, and an author absent from the list is banned by default. Exchange via `tune.module` (see convention above).
508
+
509
+
A train-on-train winner is a ceiling, never a promise: the out-of-sample section is the honest number, and the final arbiter for any point picked here is a real engine backtest (`Backtest.run`).
0 commit comments