navi-stream

name	navi-stream
description	Navi Stream language expert for writing quantitative trading indicators and technical analysis scripts. Use when working with .nvs files, technical indicators, market data analysis, or financial computations. Navi Stream is a domain-specific language optimized for real-time streaming data processing and indicator calculations.

Navi Stream Language Skill

Navi Stream (.nvs) is a domain-specific language (DSL) designed specifically for quantitative trading and technical analysis. It is optimized for real-time streaming data processing and technical indicator calculations.

Core Features

• Real-time Stream Processing - Designed for processing market data tick by tick
• Technical Indicator Library - Rich built-in technical analysis functions (ta module)
• Market Data Access - Direct access to OHLC data (quote module)
• Visualization Support - Built-in plotting functions for indicator display
• Parameterized Configuration - Support for dynamic parameters and metadata declarations
• Internationalization - Native support for multi-language labels
• Navi Integration - Can be imported and called by Navi programs

Quick Reference

Basic Structure

// 1. Metadata declaration
meta {
    title = "MACD",
    overlay = false,
}

// 2. Module imports
use quote, ta;

// 3. Parameter definition
param {
    Length1 = 12,
    Length2 = 26,
    Length3 = 9,
}

// 4. Indicator calculation
let fast_ma = ema(close, Length1);
let slow_ma = ema(close, Length2);

// 5. Export variables
export let hist = fast_ma - slow_ma;
export let signal = ema(hist, Length3);
export let macd = (hist - signal) * 2;

Key Syntax Rules

• File extension: .nvs
• Use 4 spaces for indentation
• Single-line comments: //
• String interpolation: `value: ${x}`
• Variable declaration: let (immutable), var (mutable)

Metadata System

Meta Block

meta {
    title = "Indicator Name",
    overlay = false,        // false: separate window, true: overlay on price chart
    hideparams = true,      // Hide parameter panel
}

Parameter Declaration

param {
    // Simple parameter
    Period = 14,

    // Parameter with metadata
    @meta(title = "MA Period", range = 1..250)
    MA_Period = 20,

    // Multiple parameters
    Short = 12,
    Long = 26,
    Signal = 9,
}

// Use parameters in code
let ma = ema(close, Period);

Internationalization Labels

@title_period {
    "en" = "Period",
    "zh-CN" = "周期",
    "zh-HK" = "週期",
}

// Use label
param {
    @meta(title = @title_period)
    period = 14,
}

Market Data Access (quote module)

Built-in Data Fields

use quote;

// Access current period data
let current_price = close;
let high_price = high;
let low_price = low;
let open_price = open;
let vol = volume;
let amt = turnover;

// Access historical data (time series)
let prev_close = close[1];      // Previous period
let prev_high = high[2];        // 2 periods ago

Available data fields:

• close - Close price
• open - Open price
• high - High price
• low - Low price
• volume - Volume
• turnover - Turnover
• time - Timestamp

Time Series Pattern

// Access past data
if (close > close[1]) {
    // Current close is higher than previous period
}

// Multi-period comparison
if (close > high[5]) {
    // Current price breaks above high from 5 periods ago
}

Technical Indicator Functions (ta module)

Moving Averages

use ta;

// Simple moving average
let sma20 = ma(close, 20);

// Exponential moving average
let ema12 = ema(close, 12);
let ema26 = ema(close, 26);

// Apply to different data sources
let high_ma = ema(high, 10);
let low_ma = ema(low, 10);

Common Technical Indicators

// MACD
let diff = ema(close, 12) - ema(close, 26);
let dea = ema(diff, 9);
let macd = (diff - dea) * 2;

// Bollinger Bands logic
let mid = ma(close, 20);
let upper = mid * 1.02;
let lower = mid * 0.98;

Helper Functions

// Min and max values
let min_val = min(a, b);
let max_val = max(a, b);

// Absolute value
let abs_val = abs(diff);

// Conditional count
let count_up = count(close > open, 10);  // Number of up days in last 10 periods

// Bars since condition met
let bars = barslast(close > ma);

Plotting System

Plot Function

// Basic plotting
plot(value, title: "Title", color: #ff0000);

// Multiple series
plot(ma5, title: "MA5", color: #ddff53, key: "ma5");
plot(ma10, title: "MA10", color: #4781ff, key: "ma10");
plot(ma20, title: "MA20", color: #fc6ebc, key: "ma20");

Shape Drawing

// Draw candlestick shapes
stick(top, bottom, color, hollow: true);

// Example: Price range
if (close > open) {
    stick(high, low, #red, hollow: false);
}

// Fill area
fill(upper, lower, #blue);

// Polyline
polyline(value, #green);

Text Annotation

// Draw text at specified position
if (buy_signal) {
    drawtext(close * 0.95, "Buy", #red);
}

if (sell_signal) {
    drawtext(close * 1.05, "Sell", #green);
}

Variables and Types

Variable Declaration

// Immutable variable
let price = close;
let ma = ema(close, 20);

// Mutable variable
var counter = 0;
var sum: number = 0.0;

// Export variable (becomes indicator output)
export let signal = cross_signal;
export let macd = macd_value;

Basic Types

// Number type (floating point)
let price: number = 100.5;
let volume: number = 1000000;

// Boolean
let is_up = close > open;
let crossed = cross_over(fast, slow);

// String
let message = "Hello";
let label = `Price: ${close}`;

// nil (null value)
let optional_value: number = nil;

// Color
let red = #ff0000;
let blue = #0000ff;
let green = #00ff00;

Array Operations

// Create array
var values = array.new::<number>();

// Array operations
if (barstate.is_confirmed) {
    values.unshift(close);  // Insert at beginning
}

let first = values.get(0);   // Get element
let length = values.len();   // Get length

// Iterate array
for (let i in 0..values.len()) {
    let val = values.get(i);
}

Control Flow

Conditional Statements

// if-else
if (close > open) {
    stick(high, low, #red);
} else if (close < open) {
    stick(high, low, #green);
} else {
    stick(high, low, #gray);
}

// Conditional plotting
if (close > ma20) {
    plot(close, color: #red);
}

Loops

// Range loop
for (let i in 1..10) {
    sum += values.get(i);
}

// Calculate minimum
let min_val: number = values.get(0);
for (let i in 1..min(n, values.len())) {
    min_val = min(min_val, values.get(i));
}

Function Definition

// Custom function
fn calc_average(x: number, y: number): number {
    return (x + y) / 2;
}

// Function with state
fn dllv(x: number, n: number): number {
    var values = array.new::<number>();
    if (barstate.is_confirmed) {
        values.unshift(x);
    }

    let result: number = values.get(0);
    for (let i in 1..min(n, values.len())) {
        result = min(result, values.get(i));
    }
    return result;
}

// Use function
let low_val = dllv(close, 10);

Common Patterns

Trend Detection

// Golden cross and death cross
let golden_cross = fast_ma > slow_ma && fast_ma[1] <= slow_ma[1];
let death_cross = fast_ma < slow_ma && fast_ma[1] >= slow_ma[1];

// Breakout
let breakout = close > high[20];  // Break above 20-period high
let breakdown = close < low[20];   // Break below 20-period low

Divergence Detection

// Bullish divergence: price makes new low but indicator doesn't
let price_low = dllv(close, n);
let indicator_low = dllv(diff, n);

let bullish_divergence =
    close < price_low[period] &&    // Price makes new low
    diff > indicator_low[period];    // But indicator doesn't

Multi-Period Analysis

// Short, mid, long-term trends
let short_trend = ema(close, 5);
let mid_trend = ema(close, 20);
let long_trend = ema(close, 60);

// Trend alignment
let all_up = short_trend > mid_trend && mid_trend > long_trend;
let all_down = short_trend < mid_trend && mid_trend < long_trend;

Channel System

// Price channel
let mid = ema(close, 20);
let upper = mid * 1.02;
let lower = mid * 0.98;

// Draw channel
plot(upper, color: #red);
plot(mid, color: #yellow);
plot(lower, color: #green);

// Breakout signal
if (close > upper) {
    drawtext(close, "Breakout", #red);
}

Integration with Navi

Calling NVS from Navi

// Navi code (call_macd.nv)
use nvs.macd;  // Import macd.nvs

struct Candlestick {
    time: int,
    open: float,
    high: float,
    low: float,
    close: float,
    volume: float,
    turnover: float,
}

fn main() throws {
    let indicator = macd.new();  // Create instance

    // Feed data tick by tick
    for (let candle in candlesticks) {
        indicator.execute(
            time: candle.time,
            open: candle.open,
            high: candle.high,
            low: candle.low,
            close: candle.close,
            volume: candle.volume,
            turnover: candle.turnover
        );

        // Access exported variables
        println(`hist=${indicator.hist:?}`);
        println(`signal=${indicator.signal:?}`);
        println(`macd=${indicator.macd:?}`);
    }
}

Best Practices

Naming Conventions

// Parameters: CamelCase or snake_case
param {
    ShortPeriod = 12,
    long_period = 26,
}

// Variables: snake_case
let fast_ma = ema(close, ShortPeriod);
let slow_ma = ema(close, long_period);

// Export variables: lowercase
export let signal = buy_signal;

Parameter Ranges

// Set reasonable ranges for parameters
param {
    @meta(range = 1..100)
    Period = 14,  // Limited to 1-100

    @meta(range = 1..250)
    MA_Period = 20,
}

Performance Considerations

// Good: Avoid repeated calculations
let ma20 = ema(close, 20);
let signal1 = close > ma20;
let signal2 = ma20 > ma20[1];

// Bad: Repeated calculations
let signal1 = close > ema(close, 20);
let signal2 = ema(close, 20) > ema(close, 20)[1];

Conditional Optimization

// Good: Combine conditions
let uptrend = close > ma20 && ma20 > ma60;
if (uptrend) {
    plot(close, color: #red);
}

// Use intermediate variables for readability
let price_above_ma = close > ma20;
let ma_trending_up = ma20 > ma20[1];
let strong_signal = price_above_ma && ma_trending_up;

CLI Commands

# Navi Stream runs through Navi
navi run script.nv        # Run Navi script that calls .nvs
navi build                # Build project (including nvs modules)

When to Load References

Load reference files from references/ directory when you need detailed information:

• syntax.md - Complete syntax reference
• indicators.md - Technical indicator functions in detail
• plotting.md - Plotting system detailed guide
• patterns.md - Common indicator patterns and strategies

Use Read tool to load these files from ~/.claude/skills/navi-stream/references/.

Examples Directory

The examples/ directory contains runnable code samples:

• macd.nvs - MACD indicator example
• ma_cross.nvs - Moving average crossover example
• bollinger.nvs - Bollinger Bands example
• rsi.nvs - RSI indicator example

Resources

• Navi Official Website: https://navi-lang.org
• Standard Library: https://navi-lang.org/stdlib/
• File Extension: .nvs

Important Notes

• Navi Stream focuses on indicator calculation, not general-purpose programming
• All calculations are streaming - process one data point at a time
• Exported variables become indicator outputs, displayable on charts
• When called from Navi programs, each execute() call processes one new data point