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

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/workflows.md

@@ -5,10 +5,11 @@
 - asset price, quote, or daily move → `market price`
 - supported assets, tickers, or market universe → `market assets`
 - asset performance, technicals, risk, fundamentals, or ranking → `assets overview`
+- current ordered asset lists such as Magic Formula, momentum, or user rankings → `rankings list`, then `rankings current`
 - 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`
+- indicator screening over saved asset sets → `screening universes`, `screening indicators` when needed, then `screening run`
 
 ## Find supported ticker, then get price
 
@@ -62,6 +63,28 @@ Guidance:
 
 Avoid asking for every section unless user clearly wants full report.
 
+## Get current ranked assets
+
+Use this when the user asks for an ordered list such as top Magic Formula,
+momentum leaders, dividend-yield leaders, Momentum Double, or a saved user
+ranking.
+
+```bash
+quantbrasil rankings list
+quantbrasil rankings current --system momentum-90d --top 20
+quantbrasil rankings current --system magic-formula --top 10
+quantbrasil rankings current --user 123 --top 20
+```
+
+Rules:
+
+- rankings answer order-first questions
+- system rankings use `--system <id>` from `rankings list`
+- user rankings use `--user <id>` from `rankings list`
+- do not call user rankings "factor:" in command syntax; ranking fatorial is a saved user ranking
+- use `--json` if another step needs to parse tickers, ranks, or ordering metrics
+- do not route ranking-first questions through screening unless the user asks for indicator conditions
+
 ## Analyze saved holding
 
 1. Discover holding id.
@@ -79,11 +102,13 @@ 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.
+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
@@ -94,6 +119,7 @@ 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