Skip to main content

TA Keywords — Purpose & Design (Planned)

Status

The three tables below exist in Postgres (migration a1b2c3d4e5f6, models in backend/strategies/models.py) and the Regime Master mock UI's series picker (frontend/src/pages/RegimeMaster.jsx) has been reshaped to match this structure. Nothing reads or writes the database yet - the frontend still holds its own local mock catalog (a JS array shaped like ta_keyword/ta_keyword_category rows) and no API endpoints exist. The computation registry (function_ref resolution) and the Parquet-backed value cache for precalculated bindings are still unbuilt, as originally scoped on 2026-09-12.

Problem​

The Regime Master mock lets a user pick an "input series" for a regime's rules (e.g. RSI(14) — NIFTYBEES, Nifty 50). Today that's a hardcoded array of 5 strings in the frontend. Real usage needs an open-ended, growing library of computable indicators/signals — not a fixed list baked into the UI — and the same library should be usable by Strategy Tracker and Intraday/Swing strategies, not just Asset Allocation (same "not AA-specific" principle as regimes.md).

Vocabulary​

  • Keyword — a named computation, e.g. RSI, SMA, RANGE_BREAK. Calls a function from a library (TA-Lib today; room for others/custom later). Not tied to any instrument — it's a function signature, not a value.
  • Binding — a keyword + a specific instrument (masid) + concrete parameter values. This is what actually produces a series, e.g. RSI(14) bound to NIFTYBEES = "RSI(14) — NIFTYBEES, Nifty 50". Bindings are what a regime's rule, or a strategy's condition, actually references.
  • Precalculated vs. runtime — whether a binding's values are computed ahead of time and cached, or computed on demand each time they're read. Both are keywords calling the same kind of function; this is a property of how expensive/stable the result is, not a different kind of keyword.

Three tables​

1. ta_keyword_category — open lookup, not a CHECK constraint​

regime_master.category is a 5-item CHECK IN (...) list that regimes.md already flagged as needing to grow (RSI/PE/wave/retracement don't fit). Keyword categories (the user's own example: Range Break) have the identical growth problem — new indicator families will keep showing up. Rather than repeat the CHECK-constraint mistake twice, use an open lookup table for both:

ColumnTypeNotes
idPK
codevarchar(30) uniquee.g. momentum, trend, volatility, range_break, valuation, volume, pattern
labelvarchar(60)display name
sort_orderintfor stable UI ordering

Adding a new category is an INSERT, not a migration. (Worth revisiting regime_master.category the same way at the same time, since it's the same open question.)

2. ta_keyword — the function catalog​

ColumnTypeNotes
idPK
codevarchar(30) uniqueshort identifier used in rules/UI, e.g. RSI, SMA, RANGE_BREAK, PRICE
namevarchar(100)human label, e.g. "Relative Strength Index"
category_idFK → ta_keyword_category.id
libraryvarchar(30)talib, pandas_ta, custom
function_refvarchar(150)dotted path resolved through a small registry module — never eval()/exec() on a DB value; same safety concern already flagged for Regime Master's "Custom code" tab
param_schemajsonbparameter definitions: name, type, default, min/max — e.g. {"timeperiod": {"type": "int", "default": 14, "min": 2, "max": 500}}
input_fieldsjsonbwhich OHLCV fields the function needs, e.g. ["close"] or ["high","low","close"]; [] for a keyword that needs no price series at all (e.g. India VIX, PE ratio pulled from elsewhere)
output_typevarchar(20)series | scalar | signal (boolean)
calc_modevarchar(20)default precalculated | runtime — see below; a binding can override this
descriptiontext
statusvarchar(20)active | deprecated
created_attimestamptz

One special keyword worth seeding up front: PRICE (input_fields: ["close"], function_ref resolves to an identity pass-through) — covers "just use this instrument's own price," which is what the mock's India VIX — spot option actually was, without inventing a fake indicator for every plain price series.

3. ta_keyword_binding — a keyword bound to an instrument (a usable series)​

ColumnTypeNotes
idPK
keyword_idFK → ta_keyword.id
masidinteger, soft reference to scr_master.masid — see note belowthe instrument
paramsjsonbconcrete values, overriding ta_keyword.param_schema defaults, e.g. {"timeperiod": 14}
labelvarchar(150)display string, auto-derivable (f"{keyword.name}({params}) — {master.mname}") but stored so it can be hand-edited
calc_modevarchar(20), nullableoverrides ta_keyword.calc_mode for this specific binding when needed
statusvarchar(20)active | deprecated
created_attimestamptz

masid is deliberately not a DB-level FOREIGN KEY to scr_master.masid, even though that's what it logically references. scr_master lives outside StrategyBase's metadata (see the module docstring in backend/strategies/models.py on why that base is scoped the way it is - keeping Alembic's autogenerate diff limited to the tables this migration set actually owns), and a real FK across that boundary would pull scr_master into StrategyBase's autogenerate comparisons. The column is still indexed and enforced at the application layer.

A regime's rule (the {varName, desc} objects in the current RegimeMaster.jsx mock) becomes a row referencing ta_keyword_binding.id plus the short variable name (rsi, vol21) used in that regime's condition expressions — the same join-table shape the mock's "Linked to Asset Allocation" section already anticipates for regime↔AA-plan links.

Concrete schema (as migrated)​

CREATE TABLE ta_keyword_category (
id SERIAL PRIMARY KEY,
code VARCHAR(30) NOT NULL UNIQUE,
label VARCHAR(60) NOT NULL,
sort_order INTEGER NOT NULL DEFAULT 0
);

CREATE TABLE ta_keyword (
id SERIAL PRIMARY KEY,
code VARCHAR(30) NOT NULL UNIQUE,
name VARCHAR(100) NOT NULL,
category_id INTEGER NOT NULL REFERENCES ta_keyword_category(id),
library VARCHAR(30) NOT NULL,
function_ref VARCHAR(150) NOT NULL,
param_schema JSONB NOT NULL DEFAULT '{}',
input_fields JSONB NOT NULL DEFAULT '[]',
output_type VARCHAR(20) NOT NULL,
calc_mode VARCHAR(20) NOT NULL DEFAULT 'runtime',
description TEXT,
status VARCHAR(20) NOT NULL DEFAULT 'active',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),

CONSTRAINT ck_ta_keyword_library CHECK (library IN ('talib', 'pandas_ta', 'custom')),
CONSTRAINT ck_ta_keyword_output_type CHECK (output_type IN ('series', 'scalar', 'signal')),
CONSTRAINT ck_ta_keyword_calc_mode CHECK (calc_mode IN ('precalculated', 'runtime')),
CONSTRAINT ck_ta_keyword_status CHECK (status IN ('active', 'deprecated'))
);

CREATE TABLE ta_keyword_binding (
id SERIAL PRIMARY KEY,
keyword_id INTEGER NOT NULL REFERENCES ta_keyword(id),
masid INTEGER NOT NULL, -- soft reference, see note above
params JSONB NOT NULL DEFAULT '{}',
label VARCHAR(150) NOT NULL,
calc_mode VARCHAR(20), -- NULL = inherit ta_keyword.calc_mode
status VARCHAR(20) NOT NULL DEFAULT 'active',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),

CONSTRAINT ck_ta_keyword_binding_calc_mode CHECK (calc_mode IS NULL OR calc_mode IN ('precalculated', 'runtime')),
CONSTRAINT ck_ta_keyword_binding_status CHECK (status IN ('active', 'deprecated')),
CONSTRAINT uq_ta_keyword_binding_keyword_masid_params UNIQUE (keyword_id, masid, params)
);

CREATE INDEX idx_ta_keyword_binding_keyword_id ON ta_keyword_binding(keyword_id);
CREATE INDEX idx_ta_keyword_binding_masid ON ta_keyword_binding(masid);

See migration backend/alembic/versions/a1b2c3d4e5f6_create_ta_keyword_tables.py and the TaKeywordCategory / TaKeyword / TaKeywordBinding classes in backend/strategies/models.py for the checked-in versions of the above.

Precalculated vs. runtime — storage, not schema​

Following the same split regimes.md already established (Postgres = definition, Parquet = time series): a runtime binding is computed on request straight from scr_*_eod / IEOD data and never stored. A precalculated binding is backfilled once and written to Parquet under a new data/indicators/ folder (mirroring data/regimes/ and data/nseieod/) — not a Postgres values table. ta_keyword/ta_keyword_binding stay small and slow-changing either way; only the actual number-per-day series differs in where it lives.

Example: today's 5 hardcoded options, mapped​

Old hardcoded stringkeyword.codecategorylibrarycalc_mode
RSI(14) — NIFTYBEES, Nifty 50RSImomentumtalibruntime
21-day realized volatility — NIFTYBEES, Nifty 50REALIZED_VOLvolatilitycustomruntime
PE Ratio — Nifty 50PE_RATIOvaluationcustomprecalculated (fundamentals aren't derivable from OHLC alone)
50/200 DMA crossover — Nifty 50DMA_CROSStrendcustomruntime
India VIX — spotPRICE—customprecalculated (VIX itself is a fetched series, not computed)

RANGE_BREAK (the user's own example category) isn't one of the 5 above but is the reason ta_keyword_category exists as an open lookup rather than a fixed list — a range-break trigger keyword ({"lookback": 20, "breakout_pct": 0.0} → boolean signal) drops straight into this schema without touching a CHECK constraint.

Open questions / not yet decided​

  • Where the registry module resolving function_ref → actual Python callable should live (backend/strategies/, a new backend/indicators/, or shared with the eventual regime calculation engine — same open question regimes.md has for its compute pipeline).
  • Exact Parquet partitioning under data/indicators/ for precalculated bindings.
  • Whether ta_keyword_binding.calc_mode overrides are worth the complexity vs. just living with the keyword-level default.