(barService: BarService)
| 14 | import { resolveBarSource } from './source-resolve.js' |
| 15 | |
| 16 | export function createSimulateTools(barService: BarService) { |
| 17 | return { |
| 18 | simulate: tool({ |
| 19 | description: `Backtest ONE entry + ONE exit rule over dated bars (no lookahead past asOf). Answers "if I'd bought X on date D, would <exit rule> have saved me?" — the reusable version of hand-rolling an equity path in Python. |
| 20 | |
| 21 | Exit rules (pass exitRule + its param): |
| 22 | - trailing_stop exitPct=N → exit when close falls N% from the running peak |
| 23 | - ma_break exitPeriod=N → exit on the first close below its N-bar SMA |
| 24 | - stop exitPct=N → exit when close falls N% below entry |
| 25 | - target exitPct=N → exit when close rises N% above entry |
| 26 | - hold → never exit; measure entry → asOf |
| 27 | |
| 28 | Returns entry/exit (date·price·reason), returnPct, MFE/MAE (max favorable/adverse excursion %), peak/trough, and a sampled path. open=true means no exit triggered by asOf (return is mark-to-market). Source: a barId pins one; a bare symbol/query auto-picks the freshest (realtime broker > delayed vendor).`, |
| 29 | inputSchema: z.object({ |
| 30 | query: z.string().optional().describe('Symbol/keyword — auto-picks the freshest source. Omit if barId given.'), |
| 31 | barId: z.string().optional().describe('Pin a source, e.g. "alpaca-paper|XLE". Wins over query.'), |
| 32 | asset: z.enum(['equity', 'crypto', 'currency', 'commodity']).optional().describe('Needed only for a VENDOR barId/symbol.'), |
| 33 | entryDate: z.string().describe('Enter at the close of the first bar on/after this date (YYYY-MM-DD).'), |
| 34 | exitRule: z.enum(['trailing_stop', 'ma_break', 'stop', 'target', 'hold']).describe('Which built-in exit.'), |
| 35 | exitPct: z.number().positive().optional().describe('Percent for trailing_stop / stop / target.'), |
| 36 | exitPeriod: z.number().int().positive().optional().describe('SMA period for ma_break.'), |
| 37 | interval: z.string().optional().describe('Bar interval (default "1d").'), |
| 38 | asOf: z.string().optional().describe('Evaluate up to here (YYYY-MM-DD). Default: now.'), |
| 39 | }).meta({ examples: [{ query: 'XLE', entryDate: '2026-04-01', exitRule: 'trailing_stop', exitPct: 8 }] }), |
| 40 | execute: async ({ query, barId, asset, entryDate, exitRule, exitPct, exitPeriod, interval, asOf }) => { |
| 41 | // Build the exit rule from flat params, validating the required param. |
| 42 | let exit: ExitRule |
| 43 | switch (exitRule) { |
| 44 | case 'trailing_stop': case 'stop': case 'target': |
| 45 | if (exitPct == null) return { error: `exitRule "${exitRule}" needs exitPct (a percent).` } |
| 46 | exit = { type: exitRule, pct: exitPct } |
| 47 | break |
| 48 | case 'ma_break': |
| 49 | if (exitPeriod == null) return { error: 'exitRule "ma_break" needs exitPeriod (the SMA length).' } |
| 50 | exit = { type: 'ma_break', period: exitPeriod } |
| 51 | break |
| 52 | case 'hold': |
| 53 | exit = { type: 'hold' } |
| 54 | break |
| 55 | } |
| 56 | |
| 57 | const resolved = await resolveBarSource(barService, { query, barId, asset }) |
| 58 | if ('error' in resolved) return resolved |
| 59 | |
| 60 | return simulate(barService, resolved.ref as never, { |
| 61 | entryDate, |
| 62 | exit, |
| 63 | ...(interval ? { interval } : {}), |
| 64 | ...(asOf ? { asOf } : {}), |
| 65 | }) |
| 66 | }, |
| 67 | }), |
| 68 | } |
| 69 | } |
no test coverage detected