Next Best Action (NBA) Recommendation

Learn from past user interactions to recommend the next best action — channel, send time, or offer — for every customer, every time.

The NBA workflow from Treasure AI's machine learning platform (AI Signal) looks at how your users have responded to past marketing actions and learns which action is most likely to work for each user the next time around. Instead of sending the same email, offer, or channel to everyone, NBA matches each user's context (who they are, what device they use, how they've behaved) to the action they're most likely to engage with. The result plugs into Treasure AI Master Segments and Journey orchestration so marketers and CRM teams can personalize at scale without writing policy rules by hand.

Under the hood, NBA is a contextual bandit — a model family built for explore/exploit decisions. It reads historical interaction logs, evaluates many candidate policies offline, and picks the one most likely to outperform random or rules-based targeting. You don't need to hand-label "good" or "bad" actions; the reward signal (a click, an open, a purchase) is all NBA needs to improve.

Common use cases:

• Next best channel — decide whether to reach each user via email, push, SMS, or paid media
• Send time optimization — pick the time of day or day of week most likely to earn a response
• Next best offer — select the best coupon, deal, or product recommendation from a candidate set
• Content personalization — pick the subject line, hero banner, or creative variant per user
• Feature input for downstream models — use NBA recommendations as signals for CLV, churn, or lifecycle models

Who benefits most: Lifecycle marketers, CRM managers, and personalization teams who already run A/B tests but want a learned, per-user policy rather than a one-size-fits-all winner.

NBA AI Signals ships as three functions that run on the Treasure AI ML Batch API:

• nba_tune — automatically searches models, preprocessing, and evaluation settings to find the best configuration for your dataset
• nba_train — trains a chosen policy on the full dataset and saves it to model storage
• nba_predict — scores new users with a trained policy and writes the recommended best action

Most users run nba_tune once to identify a good configuration, then schedule nba_train and nba_predict on a recurring cadence.

NBA expects a user-action interaction table — one row per event, capturing who the user was, what action they saw, whether they engaged, and the context at the time.

The three functions produce different outputs. The most important for end users is the prediction output.

One row per user, containing the recommended action with the highest predicted reward.

Example prediction row:

Activate this table directly in a journey, or join it to your customer table as attributes for use in Master Segment rules.

A diagnostic table for data scientists. One row per trial across three tuning phases (preprocessing, OPE estimator selection, policy selection) plus a random baseline for comparison. Key columns include phase, phase_trial, is_best, overall_score, estimated_policy_value, ci_lower, ci_upper, and lift_vs_random_pct.

Use this table to decide which policy is worth training at full scale. A good sign: the best policy's ci_lower is above the random baseline's estimated_policy_value, and lift_vs_random_pct is positive.

A small metadata table confirming training completed. The trained policy itself is saved to managed model storage (S3) under the model_name you provided, and is retrieved by nba_predict automatically.

NBA exposes parameters across the three functions. The most common ones are listed below.

Tuning notes:

• Start with nba_tune which will tune using OCV. OCV is paper-backed, gives more reliable policy selection, and is what the team recommends for new deployments.
• epsilon controls exploration on online models. 0.1 is a reasonable default; 0.0 is pure exploitation (risky), 1.0 is pure random.
• impute_type: knn is a safe default but slow on very large tables. Try median if runtime matters.
• Set exclude_columns to drop ID-like columns, raw timestamps, or leaky features before training.

NBA supports four policy types across two categories. nba_tune will select the best for your data, but understanding them helps interpret results.

NBA AI Signals runs via the Treasure AI ML Batch API, called from Treasure Workflow. The workflow below shows the full tune → train → predict lifecycle.

# nba_signal_workflow.dig
# Treasure Workflow: NBA AI Signals (PrecisionML)
# Runs tuning, then trains the selected model, then predicts.

# Step 1: Tune — automatic search for best model and configuration
+tune:
  http>: https://ml-batch-api.treasuredata.com/v1/runs/
  method: POST
  headers:
    - authorization: ${secret:td.apikey}
    - X-TD-ML-SESSION-ID: ${session_id}
    - X-TD-ML-ATTEMPT-ID: ${attempt_id}
  store_content: true
  content:
    input_table: your_database.user_interactions
    output_table: your_database.nba_tune_results
    solution_name: nba_tune
    solution_arguments:
      action_column: "item_id"
      reward_column: "click"
      timestamp_column: "timestamp"

+tune_status:
  http>: https://ml-batch-api.treasuredata.com/v1/runs/${JSON.parse(http.last_content)['id']}/status
  method: GET
  headers:
    - authorization: ${secret:td.apikey}

# Step 2: Train — fit the selected model on the full dataset
+train:
  http>: https://ml-batch-api.treasuredata.com/v1/runs/
  method: POST
  headers:
    - authorization: ${secret:td.apikey}
    - X-TD-ML-SESSION-ID: ${session_id}
    - X-TD-ML-ATTEMPT-ID: ${attempt_id}
  store_content: true
  content:
    input_table: your_database.user_interactions
    output_table: your_database.nba_train_results
    solution_name: nba_train
    solution_arguments:
      model_name: "nba_retail_v1"      # Unique per TD account
      model_type: "lin_eps_greedy"     # Chosen from tune results
      action_column: "item_id"
      reward_column: "click"
      timestamp_column: "timestamp"
      n_predictions: 1                 # Currently supports 1 action per user
      epsilon: 0.1
      impute_type: "median"
      scaler_type: "standard"

+train_status:
  http>: https://ml-batch-api.treasuredata.com/v1/runs/${JSON.parse(http.last_content)['id']}/status
  method: GET
  headers:
    - authorization: ${secret:td.apikey}

# Step 3: Predict — score new users with the trained model
+predict:
  http>: https://ml-batch-api.treasuredata.com/v1/runs/
  method: POST
  headers:
    - authorization: ${secret:td.apikey}
    - X-TD-ML-SESSION-ID: ${session_id}
    - X-TD-ML-ATTEMPT-ID: ${attempt_id}
  store_content: true
  content:
    input_table: your_database.users_to_score
    output_table: your_database.nba_predictions
    solution_name: nba_predict
    solution_arguments:
      model_name: "nba_retail_v1"
      user_column: "user_id"
      timestamp_column: "timestamp"

+predict_status:
  http>: https://ml-batch-api.treasuredata.com/v1/runs/${JSON.parse(http.last_content)['id']}/status
  method: GET
  headers:
    - authorization: ${secret:td.apikey}

+done:
  echo>: "NBA pipeline complete. Predictions in your_database.nba_predictions"

What this workflow does:

• Step 1 — Tune: Runs OCV-based hyperparameter search over preprocessing, OPE estimators, and policies. Writes a diagnostic table. Inspect it to pick the best policy.
• Step 2 — Train: Fits the chosen policy on the full dataset and saves it to managed model storage under model_name.
• Step 3 — Predict: Loads the trained model, scores new users, and writes the recommended action per user.

In production, most teams schedule Step 1 monthly (or on major data changes) and Steps 2–3 daily.

To create and schedule this workflow, see Getting Started with Treasure Workflow.

After nba_tune finishes, this SQL pulls the best policy's lift vs. random:

SELECT
    phase,
    estimated_policy_value,
    ci_lower,
    ci_upper,
    lift_vs_random_pct
FROM your_database.nba_tune_results
WHERE run_id = '<your_run_id>'
  AND (phase = 'baseline_random'
       OR (phase = 'phase2_policy' AND is_best = 'true'));

How to interpret:

• If the best policy's ci_lower is above the random baseline's estimated_policy_value, the policy is confidently better than random. Proceed to training.
• If lift_vs_random_pct is not positive, or the confidence interval overlaps random, the model may not help. Consider more data, better features, or a different reward definition before deploying.

NBA is designed for batch workloads on the Treasure AI ML Batch API. Training scales with the number of interactions; prediction scales with the number of users.

• Training: Runtime depends on policy type, feature count, and dataset size. lin_ucb and lin_eps_greedy are the fastest; lin_ts is slower due to posterior sampling. ipw_learner speed depends on the base classifier.
• Prediction: The trained policy is frozen at predict time, so predictions parallelize cleanly. Split the input table across parallel ML Batch API calls to reduce wall-clock time for large user bases.
• Tuning: nba_tune runs many trials. Use hyperparam_tune_sample_ratio to subsample large datasets during tuning, then train the winning policy on the full data.

Detailed benchmarks are being published — reach out to your Treasure AI account team if you need sizing guidance for datasets over 100M interactions.

Training bandit models on very large datasets can run out of memory. Models like ipw_learner are especially memory-hungry — they fit a propensity classifier alongside the reward model, and both build large intermediate arrays (action distributions, estimated rewards) that grow directly with the number of training rows. Without a cap, datasets in the millions of rows can easily trigger out-of-memory (OOM) errors inside the training container.

To prevent that, the pipeline automatically subsamples before training: if your dataset exceeds the limit set for the chosen model type, it's downsampled using stratified sampling — which preserves the distribution across all actions rather than dropping some entirely. The defaults are intentionally conservative: ipw_learner caps at 1M rows (reflecting its heavier memory footprint), while the linear models (lin_ucb, lin_ts, lin_eps_greedy) cap at 5M rows.

You can override these limits per model type with a max_training_samples_per_model object:

max_training_samples_per_model:
  lin_ucb: 5000000
  lin_ts: 5000000
  lin_eps_greedy: 5000000
  ipw_learner: 1000000

Raising a limit gives the model more data to learn from, which can improve policy quality — but weigh two trade-offs first:

• Longer training times — more samples means more computation for model fitting, cross-validation, and OPE.
• Higher memory usage — exceeding the container's available memory will crash the job with an OOM error. Be especially cautious raising the limit for ipw_learner, given its heavier footprint.

We strongly recommend training with tuning results rather than defaults. During tuning, nba_tune runs an extensive hyperparameter search across preprocessing (imputation, scaling), propensity models, reward models, and OPE estimators to find the best configuration for your specific dataset. Training with those tuned hyperparameters — instead of generic defaults — typically produces a meaningfully better policy, with higher estimated value and better generalization to new data.

This is also why tuning and training are separate steps: it lets you run the expensive search once on a representative sample, then reuse the validated hyperparameters to train multiple models without re-tuning each time. Skip this step and training falls back to generic defaults that may not fit your data distribution, action space, or reward pattern well.

Point tuning_results_table at the output table from an nba_tune run (format: database.table, e.g. mydb.nba_tuning_results) to have nba_train pick up the winning configuration automatically. If you don't also set tuning_run_id, the most recent tuning run in that table is used.

During tuning, nba_tune doesn't just score each trial — it also checks whether that score rests on enough effective data to be trustworthy. That check is ESS (Effective Sample Size): a measure of how many of your historical rows actually count toward evaluating a candidate policy, once OPE reweighting is applied.

Here's why that check is necessary. OPE estimators like IPW and DR reweight each logged row by how likely the new policy would have taken the same action the old (logging) policy actually took. If the new policy behaves quite differently from the old one, only a handful of rows end up with meaningful weight — the rest barely count. So you can have 100,000 logged rows where the real signal behind an "estimated policy value" is closer to a few hundred independent observations. The trial's score can look strong while resting on a small, shaky foundation. ESS is the number that exposes that gap.

ocv_ess_config controls how strictly Phase 2 (policy selection) enforces this check. Any trial with ESS below the configured threshold is dropped during the search, instead of being allowed to win on a score that can't be trusted.

Structure:

Within each block, safety_factor scales up a dynamically calculated threshold (based on action coverage and data distribution) — the higher the value, the more trials get rejected. The defaults differ by estimator because each tolerates distribution shift differently: ipw: 2.0, dr: 1.5, dros: 1.5, snipw: 1.0. dm is disabled by default, since the Direct Method doesn't reweight by propensity and ESS doesn't apply to it the same way.

Example — tighten filtering for IPW and DR:

ocv_ess_config:
  enabled: true
  min_ess_threshold: 20.0   # raise the global floor
  ipw:
    safety_factor: 3.0      # more conservative for IPW
  dr:
    safety_factor: 2.0      # more conservative for DR

Example — give SNIPW a lower bar, since it can work reliably with fewer samples:

ocv_ess_config:
  enabled: true
  snipw:
    safety_factor: 1.0
    min_ess_threshold: 5.0

Reading the result: every trial's calculated ESS is written to the nba_tune output table as phase2_ess (see nba_tune output (OCV mode)). Check it alongside estimated_policy_value and lift_vs_random_pct — a big lift number paired with a low phase2_ess is a reason to double-check before shipping, not a green light.

When to adjust this: leave ocv_ess_config at its defaults in most cases. It's worth revisiting if:

• Trials keep getting rejected and tuning isn't converging on a policy — this often means thin action coverage. Try lowering min_ess_threshold, or a specific estimator's safety_factor, rather than turning filtering off entirely.
• You want extra confidence before a production rollout — raise safety_factor (or min_ess_threshold) so only the most robust trials survive.

• Reward design is your responsibility — and it's critical. NBA can only learn what you tell it to optimize. A reward that's too sparse (e.g., only purchases) will make the model learn slowly; a reward that's too dense but weakly correlated with business value (e.g., any page view) will mislead it. Start with a clear, binary business outcome and iterate.
• Works best with good action coverage. If a candidate action only appears a handful of times in your logs, NBA can't reliably evaluate whether a new policy that chooses it would do well. Aim for at least a few hundred interactions per action, ideally more.
• Sparse-reward datasets are harder. When positive rewards are very rare (< 1% of rows), both propensity and reward models become less reliable, which in turn weakens the off-policy evaluation. More data and stronger features help.
• Does not currently handle cold-start actions. Adding a brand-new action with no history requires retraining from scratch. Hybrid approaches with shared weights across actions are on the roadmap.
• Batch only. NBA runs as scheduled batch jobs, not real-time inference. Sub-daily cadence is supported via frequent workflow runs, but true millisecond serving is out of scope.
• Offline evaluation has inherent uncertainty. Off-policy evaluation corrects for the gap between the logging policy and the candidate policy, but the correction is only as good as the propensity and reward models underneath it. Always A/B test a new policy against the incumbent before full rollout.
• Negative rewards require a different learner. The current online models assume non-negative rewards. Use cases that need true negative penalties (e.g., unsubscribes) need a different policy class — contact your Treasure AI team if this applies.