@quantbrasil/cli 0.1.0-beta.6 → 0.1.0-beta.8

package/skills/quantbrasil/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: quantbrasil
-description: Go-to QuantBrasil market and investing skill. Use for supported asset lookup, prices, asset analysis, watchlists, holdings, and risk/return metrics through the QuantBrasil CLI.
+description: Use this skill when a user asks for QuantBrasil-supported market or investing data/actions through the QuantBrasil CLI, including asset lookup, prices, asset analysis, watchlists, holdings, screening, historical return, beta, and VaR, even if they do not explicitly mention QuantBrasil.
 ---
 
 # QuantBrasil CLI
 
-Use this skill when the user asks for market or investing data/actions that QuantBrasil supports, including asset lookup, prices, asset analysis, watchlists, holdings, and holding metrics.
+Use this skill when the user asks for market or investing data/actions that QuantBrasil supports, including asset lookup, prices, asset analysis, watchlists, holdings, screening, and holding metrics.
 
 ## Routing
 
 - Use this skill even when the user does not say "QuantBrasil" if the request fits the supported market or investing surface.
-- For QuantBrasil-supported market, asset, watchlist, holding, or holding metric data, use the CLI before generic web or finance search.
-- When the request mentions portfolios, carteiras, watchlists, holdings, target weights, positions, historical return, beta, VaR, or saved compositions, load [`references/portfolios.md`](./references/portfolios.md) before choosing commands.
+- Most end-user QuantBrasil requests are expected in pt-BR; Portuguese prompts about ativos, carteiras, cotações, screening, retorno, beta, VaR, watchlists, or Ibovespa should trigger this skill when they map to the supported CLI surface.
+- For QuantBrasil-supported market, asset, screening, watchlist, holding, or holding metric data, use the CLI before generic web or finance search.
+- When the request mentions portfolios, carteiras, watchlists, holdings, target weights, positions, historical return, beta, VaR, screening universes, or saved compositions, load [`references/portfolios.md`](./references/portfolios.md) before choosing commands.
+- When the request mentions IFR/RSI filters, sobrevendido, sobrecomprado, indicator screening, technical screening rules, or screening indicators, load [`references/screening.md`](./references/screening.md) before building the request JSON.
 - Use `quantbrasil` when available on PATH.
 - If `quantbrasil` is not found, report that the CLI binary is not on PATH and ask the user to install it or fix PATH.
 - Check readiness first: `quantbrasil --status`
@@ -23,16 +25,19 @@ Use this skill when the user asks for market or investing data/actions that Quan
   - richer asset analysis: `quantbrasil assets overview <ticker> --sections ...`
   - watchlist details and changes: `quantbrasil watchlists ...`
   - holding details and historical return: `quantbrasil holdings ...`
+  - indicator screening over saved universes: `quantbrasil screening universes|indicators|run ...`
   - holding metrics: `quantbrasil holdings historical-return|beta|var ...`
 - Use `--json` when output will be parsed by agent or script
 - Use generic web or finance search only if the CLI is unavailable, the requested data is outside the QuantBrasil-supported surface, or the user explicitly asks for an external source.
 - Do not inspect the local repo, package source, or `~/.config/quantbrasil/config.json` for normal data queries. Use CLI status/errors instead.
 
-## References
+## Reference Loading
 
-- Portfolio, watchlist, and holding semantics: [`references/portfolios.md`](./references/portfolios.md)
-- CLI surface: [`references/cli.md`](./references/cli.md)
-- Common workflows: [`references/workflows.md`](./references/workflows.md)
-- Cost-aware behavior: [`references/costs.md`](./references/costs.md)
-- Failure handling: [`references/errors.md`](./references/errors.md)
-- Unsupported / not-yet-public operations: [`references/unsupported.md`](./references/unsupported.md)
+- Load [`references/workflows.md`](./references/workflows.md) when the user describes an investing task but does not name an exact command, or when a task spans discovery plus a follow-up action.
+- Load [`references/cli.md`](./references/cli.md) when you need exact command syntax, flags, examples, or supported `--sections` values.
+- Load [`references/portfolios.md`](./references/portfolios.md) when the request mentions portfolios, carteiras, watchlists, holdings, target weights, positions, historical return, beta, VaR, screening universes, or saved compositions.
+- Load [`references/screening.md`](./references/screening.md) when the user asks for IFR/RSI filters, sobrevendido/sobrecomprado assets, indicator screening, technical filter JSON, screening indicators, or examples of `ScreenerRequest`.
+- Load [`references/costs.md`](./references/costs.md) before chaining heavy reads, choosing between overview/screening/holding metrics, or answering cost-sensitive agent workflow questions.
+- Load [`references/errors.md`](./references/errors.md) when a CLI command fails, auth/config is unclear, or the user asks how to fix a QuantBrasil CLI error.
+- Load [`references/unsupported.md`](./references/unsupported.md) when the user asks for deletion, file export, ad-hoc ticker-list screening, unsupported commands, or a capability that may not be public yet.
+- Use [`references/quality-eval-queries.json`](./references/quality-eval-queries.json) only when evaluating or tuning skill quality and trigger accuracy.

package/skills/quantbrasil/references/cli.md

@@ -77,3 +77,56 @@ quantbrasil holdings var 182 --years 1 --confidence 95
 ```
 
 Use `--json` on any holding metric command when machine parsing needed.
+
+## Screening
+
+```bash
+quantbrasil screening universes
+quantbrasil screening indicators
+quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening.json
+quantbrasil screening run --watchlist 93 --query-file ./screening.json --limit 25
+quantbrasil screening run --holding 182 --query-file ./screening.json --sort ticker
+cat ./screening.json | quantbrasil screening run --system etfs --query-file -
+```
+
+Rules:
+
+- use exactly one selector: `--system`, `--watchlist`, or `--holding`
+- `--system` accepts a slug from `screening universes`
+- `--watchlist` and `--holding` accept numeric ids
+- `--query-file` must contain the full backend `ScreenerRequest` JSON shape
+- `--query-file -` reads the same JSON shape from stdin
+- `--limit` and `--sort` override only top-level fields from the query JSON
+- use `screening indicators` to discover supported indicator names, params, examples, timeframes, and operators
+
+Load [`screening.md`](./screening.md) for detailed screening examples, including
+IFR14, IFR2, and logical `AND` JSON payloads.
+
+Example query JSON:
+
+```json
+{
+  "query": {
+    "comparison": {
+      "left": {
+        "indicator": {
+          "name": "RSI",
+          "timeframe": "D1",
+          "offset": 0,
+          "params": {
+            "period": 14
+          }
+        }
+      },
+      "operator": "lt",
+      "right": {
+        "constant": {
+          "value": 30
+        }
+      }
+    }
+  },
+  "limit": 50,
+  "sort": "ticker"
+}
+```

package/skills/quantbrasil/references/costs.md

@@ -13,14 +13,19 @@ Current guidance uses backend qualitative classes only:
 - `market assets` is lowest-cost discovery path
 - `market price` is narrow read path
 - `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
 - holding metrics (`historical-return`, `beta`, `var`) are heaviest current public reads
 
 ## Agent rules
 
 - prefer narrow command that answers question
 - prefer `market price` over `assets overview` for quote-only requests
+- 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
 - prefer one holding metric call targeted to actual question
-- do not chain multiple heavy holding metric calls unless user asked for them
+- do not chain multiple heavy holding metric or screening calls unless user asked for them
 - use `--json` only when structured output needed
 
 ## Safe defaults

package/skills/quantbrasil/references/portfolios.md

@@ -1,8 +1,8 @@
 # Portfolio Reference
 
 Use this reference whenever the user mentions portfolios, carteiras, holdings,
-watchlists, target weights, positions, historical return, beta, VaR, risk, or a
-saved composition.
+watchlists, target weights, positions, historical return, beta, VaR, risk,
+screening universes, or a saved composition.
 
 ## Domain model
 
@@ -11,8 +11,14 @@ saved composition.
   is not an investable composition and does not define weights or positions.
 - `Holding` is a portfolio used as an investable composition. It can be based on
   target weights or positions.
+- `System Portfolio` is a backend-managed portfolio-backed universe exposed by
+  slug for screening discovery and runs.
+- `Screening Universe` is exactly one system portfolio, watchlist, or holding
+  selected for indicator screening.
 - A theoretical portfolio is a holding with target weights. Save it first, then
   run metrics on the returned holding id.
+- A holding used as a screening universe contributes only its asset set; target
+  weights and positions do not affect indicator screening.
 - Target weights and positions are independent: target weights describe intended
   allocation, while positions describe actual ownership.
 - Position quantities are shares, units, or coin amounts. Do not pass monetary
@@ -24,6 +30,10 @@ saved composition.
   non-investable saved lists.
 - Use `quantbrasil holdings ...` for investable compositions, target weights,
   positions, historical return, beta, VaR, and risk/return checks.
+- Use `quantbrasil screening universes` to discover system portfolios,
+  watchlists, and holdings available for screening.
+- Use `quantbrasil screening run` with exactly one selector to run indicator
+  screening over that selected asset set.
 - Use `quantbrasil holdings list` when the user names a saved holding but does
   not provide an id.
 - Use `quantbrasil watchlists list` when the user names a saved watchlist but
@@ -36,6 +46,7 @@ Do not use these patterns:
 - `quantbrasil portfolios ...`
 - `quantbrasil analytics ...`
 - ad-hoc asset lists passed directly into metric commands
+- ad-hoc asset lists passed directly into screening commands
 - running holding metrics on a watchlist
 
 ## Holdings

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

@@ -0,0 +1,127 @@
+[
+  {
+    "query": "Qual foi o último preço da PETR4 no QuantBrasil?",
+    "should_trigger": true,
+    "expected_behavior": "Use quantbrasil market price PETR4 before generic web or finance search."
+  },
+  {
+    "query": "Mostra o preço e a análise técnica da VALE3.",
+    "should_trigger": true,
+    "expected_behavior": "Use assets overview with the price and technicals sections."
+  },
+  {
+    "query": "Quero preço, fundamentos e rankings de ITUB4.",
+    "should_trigger": true,
+    "expected_behavior": "Use assets overview with only valid sections: price,fundamentals,rankings."
+  },
+  {
+    "query": "Mostra valuation e resumo da PETR4 pela CLI.",
+    "should_trigger": true,
+    "expected_behavior": "Do not pass invalid sections like valuation or summary; inspect capabilities or explain the supported asset overview sections."
+  },
+  {
+    "query": "Crie uma watchlist chamada Dividendos e adicione PETR4 e VALE3.",
+    "should_trigger": true,
+    "expected_behavior": "Use watchlists create followed by watchlists add-assets with explicit tickers."
+  },
+  {
+    "query": "Atualize os pesos alvo da carteira Longo Prazo para PETR4 50 e VALE3 50.",
+    "should_trigger": true,
+    "expected_behavior": "Resolve the holding id if needed, then use holdings set-targets; do not use a generic portfolio command."
+  },
+  {
+    "query": "Liste minhas carteiras e calcule o retorno histórico da carteira Longo Prazo.",
+    "should_trigger": true,
+    "expected_behavior": "Use holdings list to resolve the saved holding, then holdings historical-return."
+  },
+  {
+    "query": "Qual é o beta da minha carteira contra o Ibovespa?",
+    "should_trigger": true,
+    "expected_behavior": "Use holdings beta for a saved holding; do not calculate beta for a watchlist."
+  },
+  {
+    "query": "Quais universos salvos eu posso usar no screening de indicadores?",
+    "should_trigger": true,
+    "expected_behavior": "Use screening universes and present system portfolios, watchlists, and holdings."
+  },
+  {
+    "query": "Quais indicadores posso usar no screening?",
+    "should_trigger": true,
+    "expected_behavior": "Use screening indicators and present supported indicator names, params, examples, timeframes, and operators."
+  },
+  {
+    "query": "Rode um screening de IFR na carteira do sistema Ações Mais Líquidas.",
+    "should_trigger": true,
+    "expected_behavior": "Use screening run with one explicit --system selector and a ScreenerRequest JSON payload."
+  },
+  {
+    "query": "A CLI retornou auth_failed quando tentei buscar PETR4.",
+    "should_trigger": true,
+    "expected_behavior": "Load error guidance; explain auth login or QUANTBRASIL_API_KEY without inspecting credential files."
+  },
+  {
+    "query": "A CLI disse rate_limited ao rodar várias métricas de carteira.",
+    "should_trigger": true,
+    "expected_behavior": "Load errors and costs guidance; avoid retry loops and recommend waiting or narrowing heavy calls."
+  },
+  {
+    "query": "Meu terminal diz quantbrasil: command not found.",
+    "should_trigger": true,
+    "expected_behavior": "Report that the CLI binary is not on PATH and ask the user to install it or fix PATH; do not inspect the repo."
+  },
+  {
+    "query": "Apague uma carteira salva da minha conta.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance and explain that deleting holdings is not public in the CLI."
+  },
+  {
+    "query": "Exporte uma resposta JSON grande para arquivo usando a CLI.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance and explain that --output file export is not public yet."
+  },
+  {
+    "query": "Rode um filtro com estes tickers avulsos: PETR4, VALE3 e BBAS3.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance; do not invent ad-hoc ticker-list screening."
+  },
+  {
+    "query": "What's the latest PETR4 price in QuantBrasil?",
+    "should_trigger": true,
+    "expected_behavior": "Use quantbrasil market price PETR4."
+  },
+  {
+    "query": "Show me the price and technical overview for VALE3.",
+    "should_trigger": true,
+    "expected_behavior": "Use assets overview with price and technicals sections."
+  },
+  {
+    "query": "Run a screen over these ad-hoc tickers: PETR4, VALE3, BBAS3.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance; do not invent ad-hoc ticker-list screening."
+  },
+  {
+    "query": "Implemente um novo comando na CLI dentro do repositório do QuantBrasil.",
+    "should_trigger": false,
+    "expected_behavior": "Handle as code implementation work, not as a market-data CLI usage task."
+  },
+  {
+    "query": "Revise este pull request procurando bugs no backend.",
+    "should_trigger": false,
+    "expected_behavior": "Handle as code review work, not as a QuantBrasil CLI data task."
+  },
+  {
+    "query": "Procure na web a cotação de hoje do dólar contra o real.",
+    "should_trigger": false,
+    "expected_behavior": "Use external lookup because the user explicitly requested the web and this is not a QuantBrasil-supported asset workflow."
+  },
+  {
+    "query": "Explique conceitualmente o que significa beta de uma carteira.",
+    "should_trigger": false,
+    "expected_behavior": "Answer conceptually; no CLI call is needed unless the user asks for a saved holding metric."
+  },
+  {
+    "query": "Monte uma planilha para meus gastos mensais.",
+    "should_trigger": false,
+    "expected_behavior": "Use spreadsheet/document workflow, not the QuantBrasil CLI skill."
+  }
+]

package/skills/quantbrasil/references/screening.md

@@ -0,0 +1,212 @@
+# Screening
+
+Use screening for indicator filters over saved QuantBrasil universes.
+
+## Discovery
+
+```bash
+quantbrasil screening universes
+quantbrasil screening indicators
+```
+
+Use `screening universes` to pick the asset set. The CLI supports only saved,
+portfolio-backed universes:
+
+- system portfolios via `--system <slug>`
+- watchlists via `--watchlist <id>`
+- holdings via `--holding <id>`
+
+Do not invent ad-hoc ticker-list screening. If the user gives loose tickers,
+explain that this CLI slice only screens saved universes.
+
+Use `screening indicators` before building JSON when the indicator name,
+parameters, timeframes, or comparison operators are unclear.
+
+## Common Portuguese mappings
+
+- `IFR`, `IFR14`, `IFR(14)` -> `RSI` with `params.period = 14`
+- `IFR2`, `IFR(2)` -> `RSI` with `params.period = 2`
+- `sobrevendido` usually means low RSI, commonly `< 30` or a threshold supplied by the user
+- `sobrecomprado` usually means high RSI, commonly `> 70` or a threshold supplied by the user
+- `Ações Mais Líquidas` -> system universe slug `acoes-mais-liquidas` when present in `screening universes`
+
+## Operators
+
+- `lt` means less than
+- `lte` means less than or equal to
+- `gt` means greater than
+- `gte` means greater than or equal to
+- `eq` means equal to
+- `neq` means not equal to
+
+## IFR14 abaixo de 25
+
+```json
+{
+  "query": {
+    "comparison": {
+      "left": {
+        "indicator": {
+          "name": "RSI",
+          "timeframe": "D1",
+          "offset": 0,
+          "params": {
+            "period": 14
+          }
+        }
+      },
+      "operator": "lt",
+      "right": {
+        "constant": {
+          "value": 25
+        }
+      }
+    }
+  },
+  "limit": 500,
+  "sort": "ticker"
+}
+```
+
+Run it:
+
+```bash
+quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening-ifr14-lt-25.json
+```
+
+For agent/script parsing:
+
+```bash
+quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening-ifr14-lt-25.json --json
+```
+
+## IFR14 acima de 70
+
+```json
+{
+  "query": {
+    "comparison": {
+      "left": {
+        "indicator": {
+          "name": "RSI",
+          "timeframe": "D1",
+          "offset": 0,
+          "params": {
+            "period": 14
+          }
+        }
+      },
+      "operator": "gt",
+      "right": {
+        "constant": {
+          "value": 70
+        }
+      }
+    }
+  },
+  "limit": 500,
+  "sort": "ticker"
+}
+```
+
+## IFR2 abaixo de 10
+
+```json
+{
+  "query": {
+    "comparison": {
+      "left": {
+        "indicator": {
+          "name": "RSI",
+          "timeframe": "D1",
+          "offset": 0,
+          "params": {
+            "period": 2
+          }
+        }
+      },
+      "operator": "lt",
+      "right": {
+        "constant": {
+          "value": 10
+        }
+      }
+    }
+  },
+  "limit": 500,
+  "sort": "ticker"
+}
+```
+
+## Exemplo com AND lógico
+
+Este exemplo filtra ativos com fechamento acima da média móvel de 20 períodos e
+IFR14 abaixo de 30.
+
+```json
+{
+  "query": {
+    "logical": {
+      "op": "AND",
+      "expressions": [
+        {
+          "comparison": {
+            "left": {
+              "indicator": {
+                "name": "OHLC",
+                "timeframe": "D1",
+                "offset": 0,
+                "params": {
+                  "price_type": "close"
+                }
+              }
+            },
+            "operator": "gt",
+            "right": {
+              "indicator": {
+                "name": "RollingWindow",
+                "timeframe": "D1",
+                "offset": 0,
+                "params": {
+                  "window": 20,
+                  "method": "mean"
+                }
+              }
+            }
+          }
+        },
+        {
+          "comparison": {
+            "left": {
+              "indicator": {
+                "name": "RSI",
+                "timeframe": "D1",
+                "offset": 0,
+                "params": {
+                  "period": 14
+                }
+              }
+            },
+            "operator": "lt",
+            "right": {
+              "constant": {
+                "value": 30
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "limit": 100,
+  "sort": "ticker"
+}
+```
+
+## Stdin
+
+Use stdin when creating the JSON dynamically:
+
+```bash
+cat ./screening-ifr14-lt-25.json | quantbrasil screening run --system acoes-mais-liquidas --query-file -
+```

package/skills/quantbrasil/references/unsupported.md

@@ -5,6 +5,7 @@ Unsupported in the public CLI:
 - `--output <file>` response export
 - deleting watchlists or holdings
 - value-based position input for traded assets
+- ad-hoc ticker-list screening
 
 Not a supported pattern:
 
@@ -19,5 +20,6 @@ Use the public surface only:
 - `capabilities`
 - `market`
 - `assets`
+- `screening`
 - `watchlists`
 - `holdings`

package/skills/quantbrasil/references/workflows.md

@@ -8,6 +8,7 @@
 - watchlist details or changes → `watchlists ...`
 - 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`
 
 ## Find supported ticker, then get price
 
@@ -75,6 +76,29 @@ quantbrasil holdings beta 93 --years 1
 quantbrasil holdings var 93 --years 1 --confidence 95
 ```
 
+## Run indicator screening
+
+1. Discover available universes.
+2. Discover available indicators when the filter JSON is not already known.
+3. Pick exactly one system portfolio, watchlist, or holding.
+4. Run screening with a full `ScreenerRequest` JSON file.
+
+```bash
+quantbrasil screening universes
+quantbrasil screening indicators
+quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening.json
+quantbrasil screening run --watchlist 93 --query-file ./screening.json --limit 25
+quantbrasil screening run --holding 182 --query-file ./screening.json --sort ticker
+```
+
+Rules:
+
+- screening universes are portfolio-backed only: system portfolios, watchlists, or holdings
+- a holding used as a screening universe contributes only its asset set
+- do not invent ad-hoc ticker-list screening commands
+- load `references/screening.md` for IFR/RSI examples and full JSON payloads
+- use `--json` when the result will be parsed by an agent or script
+
 ## Analyze a theoretical composition
 
 Create a holding with target weights, then run holding metrics on its id.