@kuandotdev/indicator 0.1.1 → 0.1.3

package/project/skills/pinescript-v6/reference/v6-language.md

@@ -0,0 +1,202 @@
+# PineScript v6 — language reference (condensed)
+
+This is a **task-oriented** reference, not a full spec. For anything not here, see
+TradingView's official docs at https://www.tradingview.com/pine-script-docs/.
+
+## Script types
+
+```pinescript
+//@version=6
+indicator("My Indicator", overlay=true, max_bars_back=500)
+// or
+strategy("My Strategy", overlay=true, initial_capital=10000, currency=currency.USD,
+         default_qty_type=strategy.percent_of_equity, default_qty_value=10,
+         commission_type=strategy.commission.percent, commission_value=0.05,
+         process_orders_on_close=true)
+// or
+library("MyLib", overlay=false)
+```
+
+Key `indicator()` / `strategy()` params:
+- `overlay=true` → draws on the price chart; `false` → separate pane
+- `max_bars_back=N` → how far back historical references can look (default 244; raise if you reference `close[300]` etc.)
+- `max_lines_count`, `max_labels_count`, `max_boxes_count`, `max_polylines_count` → limits for drawing objects
+- `precision=N` → decimal places for displayed values
+
+## Types
+
+| Type | Example literal | Notes |
+|---|---|---|
+| `int` | `42`, `na` | |
+| `float` | `1.5`, `na` | NaN-aware: use `na(x)` not `x == na` |
+| `bool` | `true`, `false` | |
+| `string` | `"hello"` | Concat with `+` |
+| `color` | `color.red`, `#FF0000`, `color.rgb(255, 0, 0, 50)` | last arg is transparency 0-100 |
+| `series` | any of above but varies per bar | most TA outputs |
+
+**Type qualifiers** (in order of restrictiveness):
+- `const` → known at compile time
+- `input` → known after script loads
+- `simple` → fixed during the script's life
+- `series` → may change every bar
+
+A function expecting `simple int` cannot receive a `series int`. Common error.
+
+## Variables
+
+```pinescript
+// Reassigned every bar
+length = input.int(14, "Length", minval=1)
+
+// Persistent across bars (initialized once)
+var float last_high = na
+if high > nz(last_high, 0)
+    last_high := high
+
+// Re-initialized every bar (default)
+ma = ta.sma(close, length)
+```
+
+`:=` reassigns; `=` declares.
+
+## Conditionals & loops
+
+```pinescript
+// if as expression
+trend = close > open ? "up" : "down"
+
+// if as statement
+if close > open
+    label.new(bar_index, high, "up")
+else if close < open
+    label.new(bar_index, low, "down")
+
+// for
+sum = 0.0
+for i = 0 to length - 1
+    sum += close[i]
+avg = sum / length
+
+// while
+i = 0
+while i < 10 and close[i] > 0
+    i += 1
+
+// for...in (arrays)
+arr = array.from(1, 2, 3, 4)
+total = 0
+for v in arr
+    total += v
+```
+
+## Functions
+
+```pinescript
+// User-defined function
+my_avg(src, len) =>
+    sum = 0.0
+    for i = 0 to len - 1
+        sum += src[i]
+    sum / len
+
+// With explicit parameter types
+weighted(simple int len, series float src) =>
+    ta.wma(src, len)
+
+// Method-style on user types (v6)
+type Point
+    float x
+    float y
+
+method dist(Point self, Point other) =>
+    math.sqrt(math.pow(self.x - other.x, 2) + math.pow(self.y - other.y, 2))
+```
+
+## Collections
+
+```pinescript
+// Array
+var float[] highs = array.new<float>(0)
+array.push(highs, high)
+if array.size(highs) > 100
+    array.shift(highs)
+
+// Or with the literal form
+nums = array.from(1.0, 2.0, 3.0)
+
+// Map (v5+)
+var map<string, float> levels = map.new<string, float>()
+map.put(levels, "support", 100.0)
+support = map.get(levels, "support")
+
+// Matrix
+var m = matrix.new<float>(3, 3, 0.0)
+matrix.set(m, 0, 0, 1.0)
+```
+
+## Multi-timeframe data (`request.security`)
+
+```pinescript
+// CORRECT — explicit lookahead off, no repaint
+htf_close = request.security(syminfo.tickerid, "1D", close,
+                              lookahead=barmerge.lookahead_off)
+
+// To get confirmed HTF values without repainting, offset by [1]
+htf_close_confirmed = request.security(syminfo.tickerid, "1D", close[1],
+                                        lookahead=barmerge.lookahead_on)
+```
+
+Rule of thumb: **`lookahead_off` (no offset)** OR **`lookahead_on` with `[1]` offset**.
+Anything else likely repaints.
+
+## Drawing
+
+```pinescript
+plot(close, "Close", color=color.blue, linewidth=2)
+plotshape(ta.crossover(close, ta.sma(close, 20)), "Buy",
+          shape.triangleup, location.belowbar, color.green, size=size.small)
+bgcolor(close > open ? color.new(color.green, 90) : color.new(color.red, 90))
+hline(0, "Zero", color=color.gray, linestyle=hline.style_dashed)
+
+// Dynamic objects
+if barstate.islast
+    label.new(bar_index, high, "HIGH", color=color.yellow, textcolor=color.black)
+    line.new(bar_index - 10, low, bar_index, low, color=color.red, width=2)
+```
+
+## Alerts
+
+```pinescript
+// Static condition (legacy)
+alertcondition(ta.crossover(close, ta.sma(close, 20)), "Crossover")
+
+// Dynamic alert with message — preferred for webhook integration
+if ta.crossover(close, ta.sma(close, 20))
+    alert('{"action":"buy","symbol":"' + syminfo.ticker + '","price":' +
+          str.tostring(close) + '}', alert.freq_once_per_bar_close)
+```
+
+Strategy alerts (use placeholders in the alert dialog):
+- `{{strategy.order.action}}` → "buy" / "sell"
+- `{{strategy.order.contracts}}` → size
+- `{{strategy.position_size}}`
+- `{{ticker}}`, `{{close}}`, `{{time}}`
+
+## Bar states
+
+| State | True when |
+|---|---|
+| `barstate.isfirst` | First bar in the dataset |
+| `barstate.islast` | Most recent bar (real-time chart tip) |
+| `barstate.isconfirmed` | Bar has closed |
+| `barstate.isnew` | New bar just opened |
+| `barstate.isrealtime` | Live bar (not historical) |
+| `barstate.islastconfirmedhistory` | Last historical bar before live |
+
+## Common pitfalls
+
+1. **Repainting**: any value that changes after a bar closes. Caused by `request.security` lookahead, `barstate.islast`-only logic, `var` with conditional init.
+2. **Look-ahead bias in backtests**: using `high`/`low` of the *current* bar in entry logic is fine in Pine but unrealistic if `calc_on_every_tick=true`.
+3. **`na` propagation**: `na + 1 == na`. Wrap with `nz(x, 0)` to default.
+4. **String concatenation type errors**: must convert with `str.tostring(num)`.
+5. **`max_bars_back` errors**: if you reference `close[300]` and `max_bars_back=244` (default), you get an error. Bump it.

package/project/skills/stock-model-forecast/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: stock-model-forecast
+description: Trigger or ingest the server-side Indicator xs_range model forecast and same-day analysis artifact workflow for stock-like instruments only. Use when equity/ETF/listed-fund/index-style analysis should include the 20-trading-day model forecast, when checking or writing temp/{YYYYMMDD_HHMMSS}/{target-id}/analyzed_result.md, or when the user asks for model forecast, predicted range, low_20d/high_20d, fair_value, value_gap, win-rate, IoU, or L/S rank.
+compatibility: Generic Agent Skill. Works with Pi, Claude Code, Codex-style agents, Gemini CLI, Cursor, and other agents that can run shell commands or call MCP tools.
+---
+
+# Stock Model Forecast Skill
+
+Use this skill to include the server-side xs_range model forecast in stock-like reports.
+
+The model applies to equities, ETFs/listed funds, and index proxies. It is not the default model for crypto, forex, futures, commodities contracts, or perpetual pairs such as `BINANCE:BTCUSDT`.
+
+The model runs on a server. Indicator only calls the API and normalizes the response:
+
+```bash
+training-view model forecast <SYMBOL>
+make model-forecast SYMBOL=<SYMBOL>
+```
+
+The client expects `TV_MODEL_API_URL` to point at the forecast endpoint. It sends a JSON body with `symbol`, `model_ticker`, `refresh`, and `period`. If `TV_MODEL_API_KEY` or `TV_MODEL_API_TOKEN` is set, it is sent as a bearer token. `REFRESH=1` / `--refresh` asks the server to recompute before returning a row when the API supports it.
+
+## When to load
+
+Load this skill when:
+
+- A stock-like equity/ETF/listed-fund/index report should attempt the model forecast as part of the active market-analysis workflow.
+- An analyze-style request needs to check same-day `temp/{YYYYMMDD}_*/{TARGET_ID}/analyzed_result.md` before calling the model API.
+- The user asks for "model forecast", "20d forecast", "predicted range", `xs_range`, `low_20d`, `high_20d`, `fair_value`, `value_gap`, win-rate, IoU, or L/S rank.
+
+Do not load or call this model just because the user asks for crypto, forex, futures, or commodity-contract analysis. For those instruments, record `Model forecast not applicable: xs_range model is stock/ETF/index-only` in the analysis artifact and continue with TradingView market data, news, asset metrics, and PineScript-compatible technicals. If the user explicitly asks to test the model command on an unsupported symbol, it should return a not-applicable result rather than calling the API.
+
+## Configuration
+
+Required:
+
+```env
+TV_MODEL_API_URL=https://model.example/forecast
+```
+
+Optional:
+
+```env
+TV_MODEL_API_KEY=...
+TV_MODEL_API_TOKEN=...
+TV_MODEL_API_STATUS_URL=https://model.example/status
+TV_MODEL_API_TIMEOUT=60
+```
+
+Use `api-credential-storage` to save these values when the user provides them. Never print API keys or tokens.
+
+## Ticker normalization
+
+The client normalizes common TradingView/Yahoo-style inputs before sending them to the API:
+
+| User / TV symbol | Model ticker |
+|---|---|
+| `TSLA`, `NASDAQ:TSLA` | `TSLA` |
+| `AAPL`, `NASDAQ:AAPL` | `AAPL` |
+| `SPX`, `^GSPC` | `SPX` |
+| `TWSE:0050`, `0050.TW` | `0050` |
+| `TPEX:6584`, `6584.TWO` | `6584` |
+| `BINANCE:BTCUSDT`, `BTC-USD` | unsupported by default |
+
+Supported stock-like tickers that are new to the server should be handled by the server-side dynamic/unseen-symbol path. Do not describe a stock-like symbol as fundamentally outside model coverage unless the API returns that limitation or no usable row.
+
+## Installation / verification commands
+
+```bash
+make install       # installs the API client and prepares temp/
+make model-status  # show forecast API configuration/status
+make model-setup   # validate forecast API configuration
+```
+
+## Preferred command
+
+From Indicator repo:
+
+```bash
+make model-forecast SYMBOL=NASDAQ:TSLA
+```
+
+Equivalent CLI:
+
+```bash
+conda run -n tv-indicator --live-stream --no-capture-output \
+  training-view model forecast NASDAQ:TSLA
+```
+
+JSON for machine parsing:
+
+```bash
+conda run -n tv-indicator --live-stream --no-capture-output \
+  training-view model forecast NASDAQ:TSLA --json
+```
+
+Refresh/recompute first when the server supports it:
+
+```bash
+make model-forecast SYMBOL=NASDAQ:TSLA REFRESH=1 MODEL_JSON=1
+```
+
+MCP-aware agents can call `training-view-data:model_forecast` with `symbol`, `refresh`, and `period`.
+
+## Output payload
+
+`training-view model forecast ... --json` returns the same compact contract agents should parse:
+
+```json
+{
+  "ok": true,
+  "symbol": "NASDAQ:TSLA",
+  "model_ticker": "TSLA",
+  "covered": true,
+  "model_applicable": true,
+  "model_api_url": "https://model.example/forecast",
+  "model_output": {
+    "ticker": "TSLA",
+    "class": "US_STOCK",
+    "position": "NEUTRAL",
+    "rank": 10,
+    "close": 123.45,
+    "low_20d": 111.11,
+    "high_20d": 140.0,
+    "fair_value": 124.72,
+    "value_gap": 1.03,
+    "signal": "FAIR",
+    "mean_iou": 0.52,
+    "iou60": 0.4,
+    "dir_win": 0.56
+  },
+  "row": {
+    "ticker": "TSLA",
+    "close_today": 123.45,
+    "pred_low_20d": 111.11,
+    "pred_high_20d": 140.0,
+    "directional_win_rate": 0.56
+  },
+  "run_universe_size": 20,
+  "error": null
+}
+```
+
+If `ok=false` because the API is not configured or did not return a row, do not invent model output. Surface `error` briefly and proceed without model anchors. If `model_applicable=false`, do not retry with refresh.
+
+## Analysis artifact workflow
+
+For every market analysis request, check for a same-day repo-local artifact before creating a new one:
+
+```text
+temp/{YYYYMMDD_HHMMSS}/{TARGET_ID}/analyzed_result.md
+```
+
+Recommended shell pattern:
+
+```bash
+DAY="$(date +%Y%m%d)"
+TS="$(date +%Y%m%d_%H%M%S)"
+TARGET_ID="NASDAQ_TSLA"
+EXISTING="$(find "temp" -path "temp/${DAY}_*/${TARGET_ID}/analyzed_result.md" -print -quit 2>/dev/null || true)"
+ARTIFACT="temp/${TS}/${TARGET_ID}/analyzed_result.md"
+if [ -n "$EXISTING" ]; then ARTIFACT="$EXISTING"; else mkdir -p "$(dirname "$ARTIFACT")"; fi
+```
+
+Rules:
+
+- After symbol resolution, check for `temp/{YYYYMMDD}_*/{TARGET_ID}/analyzed_result.md`.
+- If a same-day artifact exists and has a usable model payload, reuse it unless the user asked for refresh.
+- If no same-day artifact exists, create a new timestamped artifact path.
+- Write the final report plus compact research notes and applicable model payload summary into `analyzed_result.md`.
+- Do not store secrets, cookies, API keys, hidden prompts, or raw credentials.
+- Include a one-line saved path in the final report before the disclaimer.
+- If writing fails, warn briefly and continue with the report.
+
+## How to use in reports
+
+1. Resolve the symbol, classify asset class, and check current market state / latest OHLCV.
+2. Check for a same-day artifact. If it exists and has a usable model payload, reuse it unless the user asked for refresh.
+3. Call the model API after TradingView market data and before synthesis only when the instrument is stock-like and no same-day artifact/model payload exists, the payload is stale/missing, or refresh was requested.
+4. For crypto/forex/futures/perpetual/commodity-contract instruments, skip step 3 unless the user explicitly asked to test the model command; note that the model is not applicable.
+5. Parse `model_output` first when `ok=true`; it contains the compact contract: `ticker`, `class`, `position`, `rank`, `close`, `low_20d`, `high_20d`, `fair_value`, `value_gap`, `signal`, `mean_iou`, `iou60`, and `dir_win`. `row` remains available with aliases such as `pred_low_20d`, `pred_high_20d`, `directional_win_rate`, and `iou_ge_60_rate`.
+6. Determine reliability: `mean_iou >= 0.55` is high, `0.50 <= mean_iou < 0.55` is moderate, and `mean_iou < 0.50` is weak. Use `dir_win > 0.55` as a usable direction signal and ignore direction when `dir_win < 0.50`.
+7. Reconcile with technicals and news. Reliable `high_20d` can anchor TP2 near resistance; reliable `low_20d` can anchor SL/invalidation near support. If model direction conflicts with technicals/news, state the conflict explicitly.
+8. Write the final report and compact notes into the analysis artifact.
+9. In the Short Report, include the forecast range only when a row is applicable and available.
+
+## Rules
+
+- Never fabricate model output or historical accuracy.
+- Do not use predicted prices without also citing `mean_iou` or win-rate context.
+- If the API fails for a supported stock-like instrument, include the API failure summary and continue without model anchors.
+- The model horizon is 20 trading days. For intraday or 1-5 day requests, use the model only as broad bias/range context.
+- A `SHORT` basket with `UP` direction means expected absolute rise but relative underperformance versus the current run universe; flag this as relative-value context.