Operator Reference

Complete catalog of prebuilt operators across 14 roles

Overview

ClyptQ provides prebuilt operators organized across 14 roles. Every operator follows the same protocol: receive TaggedArray inputs, return TaggedArray outputs. The StatefulGraph handles all state management, buffering, and execution ordering.

Operator Roles

Role	Count	Purpose	Output
INDICATOR	138	Technical indicators (SMA, RSI, MACD, Bollinger, 60 candlestick patterns)	Numeric values
ALPHA	313	Predictive signals for future returns (21 custom + 101 Alpha101 + 191 Alpha191)	Signal in [-1, 1]
FACTOR	8	Cross-sectional systematic exposure	Rank/score per symbol
TRANSFORM	18	Cross-sectional normalization (ZScore, Rank, Neutralize)	Transformed values
OPTIMIZER	5	Portfolio weight optimization (MVO, RiskParity)	Weights summing to 1.0
POSITION	7	Position sizing and constraints (turnover, clip)	Position sizes
FILTER	6	Boolean universe selection (volume, volatility)	1.0 or 0.0
SCORE	3	Continuous ranking scores	Score per symbol
METRIC	33	Performance measurement (Sharpe, drawdown, IC)	Rolling or cumulative
BALANCE	7	Portfolio state queries (cash, equity, positions)	State values
ORDER	6	Order intention generation (spot, futures, arbitrage)	TradingIntention
SEMANTIC	3	LLM/WebSearch/Sentiment (ephemeral)	AI-generated signals
CONTROL	3	Conditional gates (if/and/or)	Gate values (0 or 1)
UTILITY	25	Data routing (Identity, Resample, Merge, Select/Drop, TopN)	Transformed data

Operator Protocol

Every operator implements a single method:

class MyOperator(BaseOperator):
    role = OperatorRole.ALPHA  # One of 14 roles

    def compute(self, data: Dict[str, TaggedArray], timestamp, context) -> TaggedArray:
        close = data["close"]  # Input from RollingBuffer
        # Your logic here
        return TaggedArray(value=result, exists=close.exists, valid=close.valid, updated=True)

Key rules:

1. Stateless — Operators must not store mutable state between ticks. The graph manages all state via RollingBuffers
2. TaggedArray in, TaggedArray out — All inputs and outputs are TaggedArrays with 4 fields (value, exists, valid, updated)
3. Declare inputs upfront — Each input is declared via Input(source, timeframe, lookback, gaps) at graph registration time

Input Specification

from clyptq.system.graph import Input

Input(
    source="FIELD:binance:futures:ohlcv:close",  # Data source
    timeframe="1h",                                # Input timeframe
    lookback=20,                                   # Bars of history to keep
    gaps="nan",                                    # Gap handling mode
)

Parameter	Type	Default	Description
source	str	required	FIELD, STATE, or node ID to read from
timeframe	str	required	Timeframe for this input (e.g., "1m", "1h", "1d")
lookback	int	1	Number of bars to keep in the circular buffer
gaps	str	"nan"	How to handle calendar gaps: "nan" (keep as-is), "skip" (valid rows only), "ffill" (forward-fill)

Gap modes explained:

• "nan" — Default. Optimal for 24/7 markets (crypto). All rows kept, non-existing rows have exists=False.
• "skip" — For markets with regular gaps (US stocks, forex). Returns only rows where exists=True. The buffer allocates extra headroom to ensure lookback valid rows.
• "ffill" — For sparse data (macro indicators, monthly releases). Forward-fills gap rows with the last valid value.

The gaps="skip" and gaps="ffill" modes are implemented and production-ready. "skip" is designed for US stock data (weekday-only trading), but since stock data collection is not yet deployed to production, it has not been exercised at scale. "nan" (the default) is used by all current crypto production strategies. Once stock data is onboarded, no operator changes are needed — only the gaps parameter on the Input spec.

See Lookback Buffers — Gap Handling for implementation details.

Category Guide

Indicators

Technical indicators computed from price/volume data.

Moving Averages

SMA, EMA, DEMA, TEMA, WMA, TRIMA, T3, KAMA, MAMA, MA, HMA, FRAMA (12)

Momentum

RSI, MACD, MOM, ROC, CMO, APO, PPO, STOCH, STOCHRSI, WILLR, ULTOSC, BOP, TRIX, CCI, etc. (17)

Trend

ADX, ADXR, AROON, SAR, ICHIMOKU, DI, PLUS_DI, MINUS_DI, etc. (12)

Volatility

ATR, NATR, BBANDS, STDDEV, TRANGE, AVGRANGE (6)

Volume

OBV, AD, ADOSC, MFI, VWAP (5)

Statistics

LINEARREG, BETA, CORREL, VAR, TSF, MINMAX, MEDIAN, etc. (26)

Candlestick Patterns

60 CDL pattern recognizers (CDLDOJI, CDLHAMMER, CDLENGULFING, etc.)

Signals

Alpha signals and factor exposures for portfolio construction.

Alphas

21 alpha signals: Momentum, RSI, Bollinger, Volume, MeanReversion, etc.

Factors

8 cross-sectional factors: Momentum, MeanReversion, Volatility, etc.

Alpha 101

101 formulaic alphas from Kakushadze (2016)

Transforms

Cross-sectional normalization and portfolio optimization.

Scalers

ZScore, Rank, MinMax, L1Norm, L2Norm, Softmax, Clip, Winsorize, etc. (11)

Neutralizers

Demean, Neutralize, BarraNeutralizer, etc. (7)

Optimizers

MVO, RiskParity, EqualWeight, ClipWeights, MaxPositions (5)

Position

WeightsToPositions, TurnoverConstraint, etc. (7)

Universe

Filtering and scoring for tradable asset selection.

Filters

VolumeFilter, VolatilityFilter, PriceFilter, CompositeFilter (6)

Scores

VolumeScore, LiquidityScore, VolatilityScore (3)

Metrics, Balance, Order, Semantic, Control

Metrics

Rolling (17) + Accumulative (16) performance metrics

Balance

Cash, equity, positions, margin queries via STATE

Order

Spot, futures, arbitrage intention generation

Semantic

LLM scoring, web search, sentiment (ephemeral)

Control

Conditional gates, AND/OR combinators

Utility

Identity, Resample, FieldMerge, SymbolSelect/Drop

Writing Custom Operators

Basic Structure

from clyptq.system.operator import BaseOperator, OperatorRole
from clyptq.system.tagged_tensor import TaggedArray

class MyAlpha(BaseOperator):
    role = OperatorRole.ALPHA

    def __init__(self, threshold: float = 0.5):
        self.threshold = threshold

    def compute(self, data, timestamp, context):
        close = data["close"]

        # Your signal logic
        returns = (close.value[-1] / close.value[0]) - 1.0
        signal = np.where(returns > self.threshold, 1.0, -1.0)

        return TaggedArray(
            value=signal,
            exists=close.exists[-1],
            valid=close.valid[-1],
            updated=True
        )

Registering in a Graph

from clyptq.system.graph import StatefulGraph, Input

graph = StatefulGraph()

# Register with inputs
graph.add_node("my_alpha", MyAlpha(threshold=0.5),
    inputs=[Input("FIELD:binance:futures:ohlcv:close", "1m", lookback=20)])

# Use output in downstream nodes
graph.add_node("signal", ZScore(),
    inputs=[Input("my_alpha", "1m", lookback=100)])

Handling TaggedArray Masks

def compute(self, data, timestamp, context):
    close = data["close"]

    # Check if data is valid before computing
    if not close.is_valid.any():
        return TaggedArray.empty(n=close.value.shape[-1])

    # Use is_fresh for freshness-sensitive logic
    fresh_mask = close.is_fresh

    # Compute only for valid symbols
    result = np.where(close.is_valid, my_computation(close.value), np.nan)

    return TaggedArray(
        value=result,
        exists=close.exists[-1] if close.value.ndim > 1 else close.exists,
        valid=close.valid[-1] if close.value.ndim > 1 else close.valid,
        updated=True
    )

Ephemeral Operators

Operators that call external APIs (LLM, web search) are marked ephemeral:

class MyLLMOperator(SemanticOperator):
    role = OperatorRole.SEMANTIC
    ephemeral = True  # Cannot reproduce outputs for backtesting

    def _compute_semantic(self, data, timestamp, context):
        # Call external API
        response = self.llm_client.complete(...)
        return self._wrap_as_tagged(scores, data)

Ephemeral operators skip backtest validation and only run in paper/live mode.

Relationship to Other Concepts

• Operator Protocol: Detailed protocol specification
• TaggedArray: The 4-field data structure all operators use
• StatefulGraph: How operators are composed into a DAG
• Lookback Buffers: How operators receive historical data
• StatefulGraph: Patterns for composing operators into strategies