TA Keywords — Purpose & Design (Planned)
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 toNIFTYBEES= "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:
| Column | Type | Notes |
|---|---|---|
id | PK | |
code | varchar(30) unique | e.g. momentum, trend, volatility, range_break, valuation, volume, pattern |
label | varchar(60) | display name |
sort_order | int | for 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
| Column | Type | Notes |
|---|---|---|
id | PK | |
code | varchar(30) unique | short identifier used in rules/UI, e.g. RSI, SMA, RANGE_BREAK, PRICE |
name | varchar(100) | human label, e.g. "Relative Strength Index" |
category_id | FK → ta_keyword_category.id | |
library | varchar(30) | talib, pandas_ta, custom |
function_ref | varchar(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_schema | jsonb | parameter definitions: name, type, default, min/max — e.g. {"timeperiod": {"type": "int", "default": 14, "min": 2, "max": 500}} |
input_fields | jsonb | which 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_type | varchar(20) | series | scalar | signal (boolean) |
calc_mode | varchar(20) | default precalculated | runtime — see below; a binding can override this |
description | text | |
status | varchar(20) | active | deprecated |
created_at | timestamptz |
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)
| Column | Type | Notes |
|---|---|---|
id | PK | |
keyword_id | FK → ta_keyword.id | |
masid | integer, soft reference to scr_master.masid — see note below | the instrument |
params | jsonb | concrete values, overriding ta_keyword.param_schema defaults, e.g. {"timeperiod": 14} |
label | varchar(150) | display string, auto-derivable (f"{keyword.name}({params}) — {master.mname}") but stored so it can be hand-edited |
calc_mode | varchar(20), nullable | overrides ta_keyword.calc_mode for this specific binding when needed |
status | varchar(20) | active | deprecated |
created_at | timestamptz |
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 string | keyword.code | category | library | calc_mode |
|---|---|---|---|---|
RSI(14) — NIFTYBEES, Nifty 50 | RSI | momentum | talib | runtime |
21-day realized volatility — NIFTYBEES, Nifty 50 | REALIZED_VOL | volatility | custom | runtime |
PE Ratio — Nifty 50 | PE_RATIO | valuation | custom | precalculated (fundamentals aren't derivable from OHLC alone) |
50/200 DMA crossover — Nifty 50 | DMA_CROSS | trend | custom | runtime |
India VIX — spot | PRICE | — | custom | precalculated (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 newbackend/indicators/, or shared with the eventual regime calculation engine — same open questionregimes.mdhas for its compute pipeline). - Exact Parquet partitioning under
data/indicators/for precalculated bindings. - Whether
ta_keyword_binding.calc_modeoverrides are worth the complexity vs. just living with the keyword-level default.