@quantbrasil/cli 0.1.0-beta.13 → 0.1.0-beta.14

package/skills/quantbrasil/references/backtests.md

@@ -0,0 +1,170 @@
+# Backtests
+
+Use backtests when the user asks to run a historical simulation for one
+supported strategy and one explicit asset.
+
+Backtests are strategy-specific. Always inspect the selected strategy before
+overriding parameters unless the user already gave exact parameter names.
+
+## Commands
+
+```bash
+quantbrasil backtests strategies
+quantbrasil backtests strategies --json
+quantbrasil backtests info ifr2
+quantbrasil backtests info ifr2 --json
+quantbrasil backtests run ifr2 PETR4 --timeframe D1 --from 2025-01-01 --to 2026-01-01
+quantbrasil backtests run ifr2 PRIO3 --timeframe D1 --param rsi=15
+quantbrasil backtests run ifr2 PETR4 --timeframe D1 --param rsi=30 --param window=2 --json
+```
+
+## Agent Workflow
+
+1. Use `backtests strategies` when the strategy id is unknown.
+2. Use `backtests info <strategy-id>` before changing parameters.
+3. Read `selection_guidance`, `timeframe_guidance`, accepted parameter names, defaults, value hints, and parameter guidance from the info output.
+4. Use `backtests run <strategy-id> <ticker>` for one strategy and one asset.
+5. Add `--json` to `backtests info` when another agent or script needs defaults; add `--json` to `backtests run` when it needs metrics, parameters, or trade history.
+
+If the user says "IFR2 on PRIO3 with value 15", map "value" to the IFR2
+threshold parameter and run:
+
+```bash
+quantbrasil backtests run ifr2 PRIO3 --timeframe D1 --param rsi=15
+```
+
+## Strategy Selection
+
+Use the strategy id returned by `backtests strategies` or `backtests info`.
+Hyphens and underscores are both accepted by the CLI and normalized before the
+request is sent.
+
+| Family               | Strategy ids                                                             | Select when                                                                                                                                       |
+| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| IFR                  | `ifr2`, `long_rsi`                                                       | The user asks for IFR/RSI, sobrevenda, sobrecompra, or mean reversion by relative strength. Prefer `ifr2` for the classic short-window IFR setup. |
+| Estocástico          | `long_stochastic`, `short_stochastic`                                    | The user asks for stochastic oscillator, sobrevendido/sobrecomprado by estocástico, or oscillator mean reversion.                                 |
+| Máximas e mínimas    | `maxmin`, `short_maxmin`                                                 | The user asks for breakout of recent highs/lows with entry and exit windows.                                                                      |
+| Padrão 123           | `long_123`, `short_123`                                                  | The user asks for pattern 123, reversal/continuation by a technical formation, or stop by candle/amplitude.                                       |
+| Candle               | `long_wick_candle`, `short_wick_candle`                                  | The user asks for wick, gap, rejection candle, or candle-body/pavio logic. These are daily/weekly strategies.                                     |
+| Reversão             | `long_turnaround`                                                        | The user asks for turnaround after a negative sequence or exhaustion move.                                                                        |
+| Trap                 | `long_trap`, `long_candle_trap`, `short_candle_trap`                     | The user asks for trap, false breakout, candle trap, or failure around a moving average/candle.                                                   |
+| PFR                  | `long_pfr`, `short_pfr`                                                  | The user asks for Preço de Fechamento de Reversão or a short reversal after failed continuation.                                                  |
+| Padrão Shark         | `long_shark`, `short_shark`                                              | The user asks for Shark pattern with configurable entry, stop, and target.                                                                        |
+| Inside Bar           | `long_insidebar`, `short_insidebar`                                      | The user asks for inside bar breakout.                                                                                                            |
+| Breakout             | `long_breakout`, `short_breakout`                                        | The user asks for candle/technical-region breakout with target by risk, percentage, or Fibonacci.                                                 |
+| Bandas de Bollinger  | `long_open_bb`, `short_open_bb`, `long_reversal_bb`, `short_reversal_bb` | Use opening-band strategies for volatility expansion; use reversal-band strategies for return from extremes.                                      |
+| Horário              | `long_by_time`, `short_by_time`                                          | The rule is to enter and exit at fixed intraday times.                                                                                            |
+| Variação atípica     | `long_atypical_variation`, `short_atypical_variation`                    | The user asks for statistically unusual moves by Z-score.                                                                                         |
+| Variação intradiária | `long_intraday_variation`, `short_intraday_variation`                    | The user asks for intraday percentage variation with entry/exit by variation. These define timeframe internally.                                  |
+| HiLo Activator       | `long_hilo_activator`, `short_hilo_activator`                            | The user asks for HiLo Activator as the trend or signal rule.                                                                                     |
+| Três médias          | `long_three_bar`, `short_three_bar`                                      | The user asks for three averages, three-bar style confirmation, or channel/average confirmation.                                                  |
+| Supertrend           | `long_supertrend`, `short_supertrend`                                    | The user asks for Supertrend or ATR-based trend following.                                                                                        |
+| Canal de Donchian    | `long_donchian`, `short_donchian`                                        | The user asks for Donchian channel breakout by high/low window.                                                                                   |
+| Gap Trap             | `long_gaptrap`, `short_gaptrap`                                          | The user asks for failed continuation after an intraday gap. Do not use for crypto assets.                                                        |
+| Saudade de Casa      | `long_sdc`, `short_sdc`                                                  | The user asks for return to reference bands after intraday displacement. Do not use for crypto assets.                                            |
+
+For direction, choose `long`/compra ids when the user asks for buying,
+recovery, upside, oversold, or upward breakout. Choose `short`/venda ids when
+the user asks for selling, downside, short, overbought, or downward breakout.
+
+## Timeframes and Dates
+
+- Most strategies require `--timeframe`; use `backtests info` to confirm.
+- Timeframe values are `M5`, `M15`, `M30`, `H1`, `H2`, `H4`, `D1`, and `W1`.
+- Daily/weekly-only strategies accept only `D1` or `W1`.
+- Intraday-only strategies accept only `M5`, `M15`, `M30`, `H1`, `H2`, or `H4`.
+- Intraday-variation strategies define timeframe internally; omit `--timeframe`.
+- If the user does not specify a timeframe for a generic equity backtest and the strategy allows daily candles, use `D1` and state that assumption.
+- `--from` and `--to` use ISO dates: `AAAA-MM-DD`.
+- When dates are omitted, backend defaults apply.
+
+## Parameter Rules
+
+- `backtests info` returns accepted parameter names, defaults, types, enum options, descriptions, `value_hint`, and `agent_guidance`.
+- Do not invent parameter names. If a user gives camelCase or kebab-case, the CLI normalizes it to snake_case.
+- `--param key=value` can be repeated. Keys may be written as `stopInDays`, `stop-in-days`, or `stop_in_days`.
+- `--params-json '{"rsi":30,"window":2}'` is useful when many parameters are set at once.
+- Values in `--param` are parsed as booleans, numbers, or strings.
+- Explicit `--param` values override matching keys from `--params-json`.
+- Prefer defaults unless the user asks to change a parameter or gives a concrete value.
+
+## Common Parameter Glossary
+
+Time controls:
+
+- `is_day_trade`: forces intraday behavior when the strategy supports it.
+- `min_open_time`: earliest intraday entry time, formatted `HH:MM`; useful for ignoring the opening auction or early volatility.
+- `close_time_limit`: latest intraday close time, formatted `HH:MM`; useful for avoiding positions after the desired trading session.
+- `entry_time`: fixed entry time for by-time strategies.
+- `exit_time`: fixed exit time for by-time strategies.
+
+Trend and filters:
+
+- `mm50_is_up`: IFR2 trend filter; `true` requires the 50-period moving average to be rising before long entries.
+- `mme80_is_up`: EMA80 directional filter used by RSI/stochastic variants.
+- `traders_eden`: proprietary trend-confirmation filter.
+- `hammer`: requires hammer/wick-style candle confirmation.
+- `inside_bar`: requires inside-bar confirmation.
+- `apply_rsi_filter`: adds RSI confirmation to supported band strategies.
+- `apply_keltner_filter`: adds Keltner-channel confirmation to supported max/min strategies.
+- `ignore_trend_confirmation`: removes the auxiliary trend confirmation when supported.
+
+Indicator thresholds and windows:
+
+- `rsi`: IFR/RSI threshold. In IFR2, lower values are more selective for long entries; for example `rsi=15`.
+- `rsi_window`: IFR/RSI calculation window.
+- `entry_rsi` and `exit_rsi`: RSI levels for entry and exit in RSI variants.
+- `k_window`: stochastic `%K` calculation window.
+- `mma_window`: moving-average smoothing window.
+- `entry_stochastic` and `exit_stochastic`: stochastic levels for entry and exit.
+- `rolling_avg_type`: `simple` or `ewm`.
+- `rolling_avg_window`: moving-average window used when entry uses a rolling average.
+
+Risk, stop, and target:
+
+- `stop`: stop rule enum. Inspect `backtests info` for allowed values on the selected strategy.
+- `target`: target/exit rule enum. Inspect `backtests info` for allowed values on the selected strategy.
+- `stop_in_days`: maximum trade duration in candles; on D1 it behaves as daily candles, on intraday it behaves as candles of that timeframe.
+- `stop_in_pct`: percentage stop as a decimal fraction, for example `0.02` for 2%.
+- `target_in_pct`: percentage target as a decimal fraction, for example `0.03` for 3%.
+- `risk_factor`: target/stop multiple for fixed-risk strategies.
+- `fibo_retracement`: Fibonacci retracement used for stop placement when supported.
+- `fibo_extension`: Fibonacci extension used for target projection when supported.
+- `max_risk`: financial risk limit. Prefer the CLI flag `--max-risk` when the user means risk in money.
+
+Statistical, channel, and volatility controls:
+
+- `zscore_threshold`: minimum absolute Z-score for atypical-variation strategies.
+- `rolling_window`: rolling calculation window for statistical strategies.
+- `std_factor`: standard-deviation multiplier used by statistical targets.
+- `stop_in_std`: stop measured in standard deviations.
+- `num_std`: number of standard deviations for Bollinger bands.
+- `atr_window` and `atr_multiplier`: ATR window and multiplier for Supertrend.
+- `top_channel_window`, `bottom_channel_window`, and `channel_window`: channel lookback windows for channel/breakout strategies.
+- `keltner_window` and `keltner_multiplier`: Keltner-channel calculation controls.
+
+Pattern-specific controls:
+
+- `body_pct`: minimum candle body fraction for wick/candle strategies.
+- `gap_pct`: minimum gap size as a decimal fraction.
+- `negative_sequence`: number of negative candles required before turnaround.
+- `exhaustion_pct`: minimum exhaustion move before a turnaround setup.
+- `candles_above`: persistence requirement above a moving average.
+- `target_band`: `middle` or `opposite` target band for Saudade de Casa.
+- `entry_variation` and `exit_variation`: intraday percentage variation thresholds. The sign matters; negative entry variation means a drop before long entry.
+- `entry_window`, `exit_window`, and `window`: generic lookback windows whose exact meaning depends on the selected strategy; inspect `backtests info` before overriding.
+
+## Output
+
+Human output summarizes return, drawdown, EV, win rate, operations, profit
+factor, score when available, and the saved backtest id.
+
+JSON output includes the full saved backtest response, including parameters and
+trade history.
+
+## Unsupported
+
+- batch backtests
+- backtest ranking across many strategies or assets
+- automatic screening-to-backtest chaining
+- comparing two saved backtests from the CLI

package/skills/quantbrasil/references/cli.md

@@ -46,6 +46,22 @@ Valid `--sections`:
 - `fundamentals`
 - `rankings`
 
+## News
+
+```bash
+quantbrasil news asset PETR4
+quantbrasil news asset PETR4 --window 7 --limit 10
+quantbrasil news asset PETR4 --json
+```
+
+Rules:
+
+- use `news asset` when the user asks for recent saved RSS news about one explicit ticker
+- `--window` is the lookback window in calendar days and defaults to `30`
+- `--limit` is the maximum number of articles and defaults to `20`
+- the response is based on direct ticker mentions stored by QuantBrasil, not sentiment or article scraping
+- use `--json` when another step needs to parse sources, dates, URLs, or mentioned tickers
+
 ## Rankings
 
 ```bash
@@ -158,6 +174,32 @@ Example query JSON:
 Load [`screening.md`](./screening.md) for detailed screening examples, including
 IFR14, IFR2, and logical `AND` JSON payloads.
 
+## Backtests
+
+```bash
+quantbrasil backtests strategies
+quantbrasil backtests strategies --json
+quantbrasil backtests info ifr2
+quantbrasil backtests info long-rsi --json
+quantbrasil backtests run ifr2 PETR4 --timeframe D1 --from 2025-01-01 --to 2026-01-01
+quantbrasil backtests run ifr2 PETR4 --timeframe D1 --param rsi=30 --param window=2
+quantbrasil backtests run long-rsi VALE3 --timeframe D1 --params-json '{"entry":"rolling_avg","rollingAvgType":"simple","rollingAvgWindow":20}'
+quantbrasil backtests run long-intraday-variation PETR4 --from 2025-01-01 --to 2025-12-31 --json
+```
+
+Rules:
+
+- use `backtests strategies` to discover strategy ids
+- use `backtests info <strategy-id>` to inspect motivation, selection guidance, timeframe guidance, accepted parameters, defaults, value hints, parameter guidance, types, options, and allowed timeframes
+- use `backtests run <strategy-id> <ticker>` for one strategy and one asset
+- use `--timeframe` unless `backtests info` says the strategy has an internal timeframe
+- `--param key=value` can be repeated; `--params-json` accepts an object of parameters
+- `--param` values override matching keys from `--params-json`
+- use `--json` when metrics, parameters, or trade history will feed another step
+- batch backtests, backtest rankings, saved-backtest comparison, and automatic screening-to-backtest chaining are not public CLI commands
+
+Load [`backtests.md`](./backtests.md) for detailed backtest workflow guidance.
+
 ## Cointegration
 
 ```bash

package/skills/quantbrasil/references/costs.md

@@ -12,10 +12,13 @@ Current guidance uses backend qualitative classes only:
 
 - `market assets` is lowest-cost discovery path
 - `market price` is narrow read path
+- `news asset` is a standard narrow read path for recent ticker news
 - `assets overview` is richer and should use minimal `--sections`
 - `screening universes` is a discovery path for saved screening universes
 - `screening indicators` is a discovery path for supported screening JSON
 - `screening run` is a heavy read and should be targeted to one selected universe
+- `backtests strategies` and `backtests info` are discovery paths
+- `backtests run` is heavy and should be targeted to one selected strategy and ticker
 - `cointegration pair` is a heavy read and should be targeted to one explicit pair
 - `rankings return` is a heavy read and should be targeted to one explicit system ranking and date range
 - holding metrics (`historical-return`, `beta`, `var`) are heaviest current public reads
@@ -24,11 +27,13 @@ Current guidance uses backend qualitative classes only:
 
 - prefer narrow command that answers question
 - prefer `market price` over `assets overview` for quote-only requests
+- prefer `news asset` over web search for QuantBrasil-supported recent ticker news
 - run `screening universes` before `screening run` when the universe selector is not known
 - run `screening indicators` before `screening run` when the indicator JSON is not known
+- run `backtests info` before changing strategy parameters
 - run `rankings list` before `rankings return` when return support or the system slug is not known
 - prefer one holding metric call targeted to actual question
-- do not chain multiple heavy holding metric, ranking return, screening, or cointegration calls unless user asked for them
+- do not chain multiple heavy holding metric, ranking return, screening, backtest, or cointegration calls unless user asked for them
 - use `--json` only when structured output needed
 
 ## Safe defaults

package/skills/quantbrasil/references/quality-eval-queries.json

@@ -14,6 +14,11 @@
     "should_trigger": true,
     "expected_behavior": "Use assets overview with only valid sections: price,fundamentals,rankings."
   },
+  {
+    "query": "Quais são as notícias recentes de PETR4?",
+    "should_trigger": true,
+    "expected_behavior": "Use quantbrasil news asset PETR4, cite source/date, and do not infer sentiment."
+  },
   {
     "query": "Mostra valuation e resumo da PETR4 pela CLI.",
     "should_trigger": true,
@@ -54,6 +59,31 @@
     "should_trigger": true,
     "expected_behavior": "Use screening run with one explicit --system selector and a ScreenerRequest JSON payload."
   },
+  {
+    "query": "Quais estratégias de backtest posso rodar pela CLI?",
+    "should_trigger": true,
+    "expected_behavior": "Use backtests strategies and present supported strategy ids; do not invent unsupported batch workflows."
+  },
+  {
+    "query": "Explique os parâmetros da estratégia IFR2 antes de rodar.",
+    "should_trigger": true,
+    "expected_behavior": "Load backtests guidance and use quantbrasil backtests info ifr2 to inspect defaults, selection guidance, timeframe guidance, value hints, parameter descriptions, and allowed timeframes."
+  },
+  {
+    "query": "Rode backtest de IFR2 para PRIO3 com valor 15.",
+    "should_trigger": true,
+    "expected_behavior": "Load backtests guidance, map the IFR2 value to rsi=15, and use quantbrasil backtests run ifr2 PRIO3 --timeframe D1 --param rsi=15 unless the user specifies another timeframe."
+  },
+  {
+    "query": "Rode um backtest de IFR2 para PETR4 no diário.",
+    "should_trigger": true,
+    "expected_behavior": "Load backtests guidance and use quantbrasil backtests run ifr2 PETR4 --timeframe D1, adding dates only if the user provides or asks for a specific period."
+  },
+  {
+    "query": "Rode backtests em lote e rankeie as melhores estratégias para PETR4.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance; explain that public CLI supports individual backtest runs, not batch backtests or strategy rankings."
+  },
   {
     "query": "Rode cointegração entre PETR4 e VALE3.",
     "should_trigger": true,

package/skills/quantbrasil/references/unsupported.md

@@ -7,6 +7,10 @@ Unsupported in the public CLI:
 - value-based position input for traded assets
 - ad-hoc ticker-list screening
 - scanning all cointegrated pairs in a universe
+- batch backtests
+- backtest rankings across many strategies or assets
+- comparing saved backtests from the CLI
+- automatic screening-to-backtest chaining
 
 Not a supported pattern:
 
@@ -22,6 +26,7 @@ Use the public surface only:
 - `market`
 - `assets`
 - `cointegration`
+- `backtests`
 - `screening`
 - `watchlists`
 - `holdings`

package/skills/quantbrasil/references/workflows.md

@@ -4,6 +4,7 @@
 
 - asset price, quote, or daily move → `market price`
 - supported assets, tickers, or market universe → `market assets`
+- recent news, headlines, or articles for one ticker → `news asset`
 - asset performance, technicals, risk, fundamentals, or ranking → `assets overview`
 - current ordered asset lists such as Magic Formula, momentum, Low Risk, or user rankings → `rankings list`, then `rankings current`
 - historical return of ranking strategies such as Magic Formula or Momentum → `rankings list`, then `rankings return`
@@ -11,6 +12,7 @@
 - holding details or changes → `holdings ...`
 - holding return, beta, risk, VaR, or comparison → `holdings historical-return|beta|var`
 - indicator screening over saved asset sets → `screening universes`, `screening indicators` when needed, then `screening run`
+- one strategy backtest for one explicit asset → `backtests strategies`, `backtests info`, then `backtests run`
 - cointegration or Long & Short between two explicit assets → `cointegration pair`
 
 ## Find supported ticker, then get price
@@ -44,6 +46,23 @@ Do not use generic web or finance search for QuantBrasil-supported market data
 unless the CLI is unavailable, the requested data is outside the supported
 surface, or the user explicitly asks for an external source.
 
+## Get recent ticker news
+
+Use this when the user asks for news, headlines, articles, or recent updates
+about one explicit ticker.
+
+```bash
+quantbrasil news asset PETR4
+quantbrasil news asset PETR4 --window 7 --limit 10
+```
+
+Rules:
+
+- news results are saved RSS items that directly mentioned supported tickers
+- cite source and publication date when summarizing results
+- do not infer sentiment or recommendations from the news list
+- use generic web search only if the user asks for external/current web research beyond QuantBrasil's stored news
+
 ## Cost-aware `assets overview` section choice
 
 Keep `--sections` minimal.
@@ -150,6 +169,30 @@ Rules:
 - do not invent a universe scan command for "quais pares cointegrados"; the public CLI currently supports explicit pairs
 - use `--json` if the z-score or beta series will feed another calculation
 
+## Run one backtest
+
+Use this when the user asks to run a historical strategy simulation for one
+explicit asset.
+
+```bash
+quantbrasil backtests strategies
+quantbrasil backtests info ifr2
+quantbrasil backtests run ifr2 PETR4 --timeframe D1 --from 2025-01-01 --to 2026-01-01
+quantbrasil backtests run ifr2 PRIO3 --timeframe D1 --param rsi=15
+quantbrasil backtests run ifr2 PETR4 --timeframe D1 --param rsi=30 --param window=2 --json
+```
+
+Rules:
+
+- use `backtests strategies` if the user names a strategy informally
+- use `backtests info` before setting or explaining parameters
+- read `selection_guidance`, `timeframe_guidance`, defaults, `value_hint`, and `agent_guidance` before choosing overrides
+- for IFR2, a generic "value" usually maps to `rsi`; for example "IFR2 on PRIO3 with value 15" means `--param rsi=15`
+- run one strategy and one asset at a time
+- do not invent batch backtests, backtest rankings, or saved-backtest comparison commands
+- do not chain screening results into backtests automatically; ask for an explicit next step when needed
+- use `--json` when another step needs the full saved backtest response or trade history
+
 ## Analyze a theoretical composition
 
 Create a holding with target weights, then run holding metrics on its id.