Action Engine

What the engine is

The engine writes typed decision rows to one table, action_decisions: one row per (ticker, horizon) per run, for the 1d, 5d, 20d and 60d horizons the model returns. Each run asks the Python pipeline for fresh LightGBM predictions, passes each horizon through the deterministic mapper MapVerdict (internal/services/action_engine/verdict_mapper.go), and inserts the rows. Same prediction in, same row out.

Model-tier parameters (an analyzer tier and a worker tier, named by vendor aliases) still thread through the scheduler and the Analyze request, but the code that consumed them was the removed reviewer, so they have no effect on a decision. The LLM roles that remain around the engine are a risk flagger and a catalyst extractor, described below; neither is an input to MapVerdict.

Trigger modes

Five trigger types are declared in internal/services/action_decisions_service.go. Only on_demand uses RunOnDemand; the other four use the worker entry point Run, which honours a live audit lock. The trigger string is stored on every row.

The risk-flagger sweep runs after each of the four scheduled sweeps. It is not a trigger type and writes no new decision rows.

Inference paths

Two paths produce model output. They are separate code, separate tables and separate consumers.

Path A feeds verdicts, the Stock feed predicates, push crossings and the Auto-Pilot paper books. Path B runs beside the legacy sweeps and produces batch-stamped cross-sectional ranks. The requester can be switched off by configuration, so a source sha does not tell you whether a batch was published on a given day.

Universe

Layer 0: cohort filters (pipeline)

Universe eligibility is decided where the models are trained and served, in the pipeline's cohort definitions (COHORT_DEFINITIONS in src/pipeline.py). Two cohorts are in production; the earlier cohorts were removed on 2026-05-15.

The scheduled sweep uses the same $2B / 500K split only to label tickers mid-large versus the rest; both groups are swept. The batch path ranks its own universe, floored at $1B market cap under the same symbol rule. Trading-halt handling is not a universe filter: it sits in the Auto-Pilot engine.

How a ticker is excluded in practice

The live run path goes audit-lock check → price-freshness refresh → predict_one. A ticker is excluded by the sweep's universe query, by the scanner queue's symbol filter, or by the pipeline returning no prediction. There is no separate engine-side gate on the run path at backend 07c641de.

Verdicts and predicates

MapVerdict turns one (horizon, predicted % return) pair into BUY, SELL or HOLD with a LARGE / MID / SMALL intensity. Magnitude bands widen with the horizon, negatives mirror positives, and a prediction of exactly zero is HOLD. The band values are not published here. One horizon per run is tagged primary (the largest weighted absolute prediction). The persisted row keeps the numeric predictions; the direction and intensity columns are no longer populated, so consumers act on the numbers through the predicates below.

Floors, ceilings and band sizes are tunable per user and are deliberately not printed. The model's output scale shifts between retrains, which is why the sell side moved from an absolute ceiling to a percentile.

• Auto-Pilot exits use a different predicate. The paper books resolve their own cross-sectional exit per strategy, not the user-facing sell_now configuration. See the Auto-Pilot page.
• Auto-Pilot entry ranking is not a verdict. Books rank candidates separately from MapVerdict.
• Push. After a run, maybeFirePushCrossing compares the new primary row with the prior one and notifies only on a false→true crossing of buy_now or sell_now, and only when the primary row is the 60d horizon. It is best-effort and never blocks the decision write.

Risk flagger gate

• The gate (FreshRiskFlagsGateSQL) reads flags across all of a ticker's recent rows, because the row a flag was written on stops being the latest at the next refresh.
• Without a qualifying fresh evaluation, the gate fails closed. A failed refresh does not invalidate an earlier evaluation that remains within the freshness window.
• The flagger is not graded against forward returns; coverage is measured, precision is not.
• It gates Auto-Pilot buys. It does not change a verdict or the Stock feed predicates.

Display-only risk / quality score

Each row also carries risk_score and quality_score: recent catalyst emissions (14-day lookback) blended with a term derived from the spread of the horizon predictions. They are computed after the verdicts and stamped on the row. They are not a verdict input, and no feed, Auto-Pilot, web or iOS path reads them; the one reader is a backtest diagnostic.

Catalysts

• Emissions are stored in llm_catalyst_emissions with the model name and the price at emit time.
• A resolver (at boot and every six hours) grades each emission once its horizon has passed, writing the realized move, a directional hit and a magnitude hit back onto the row.
• Emissions feed the risk flagger's prompt context, the display-only risk / quality score, ticker-detail and scanner cards, and the public catalyst-accuracy endpoint.
• They are not an input to verdicts. Their only route to a trading gate is two hops: emission → risk-flagger context → high-severity flag.

Decision row schema

Columns the current engine path writes on each (ticker, horizon) row:

Present but not populated by the current path: direction, intensity, size_pct (dropped from the write path in May 2026), confidence, confidence_60d, opus_model, opus_prompt_hash, tagged_facts, n_models, cohorts, and the reviewer's v2_* columns (not written since the reviewer was removed).

Caching & lineage