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

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,122 @@
+[
+  {
+    "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": "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/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`, then `screening run`
 
 ## Find supported ticker, then get price
 
@@ -75,6 +76,26 @@ quantbrasil holdings beta 93 --years 1
 quantbrasil holdings var 93 --years 1 --confidence 95
 ```
 
+## Run indicator screening
+
+1. Discover available universes.
+2. Pick exactly one system portfolio, watchlist, or holding.
+3. Run screening with a full `ScreenerRequest` JSON file.
+
+```bash
+quantbrasil screening universes
+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
+- 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.