Protocol v2 strategy_grid Migration

This note describes the NLHE strategy_grid response shape differences between the legacy v1 rangeviewer pipeline and the protocol v2 universal-poker pipeline. It intentionally does not cover PLO.

Summary

The main response-shape change is that v1 exposes the 169 range-matrix entries as top-level strategy[] items keyed by combo, while v2 exposes them as top-level hands[] items keyed by handName.

Concrete two-card combos still exist in v2, but they are nested under each hand entry in hand.combos[].

v1 Shape

In v1, each top-level strategy entry is a 169-matrix cell such as AA, AKs, or AKo.

{
  "strategy": [
    {
      "combo": "AKs",
      "strategy": [0.1, 0.2],
      "reach": 1.0,
      "ev": 0.4,
      "detail": [
        {
          "combo": "AsKs",
          "reach": 1.0,
          "detail": [["fold", "10.0%", "-1.00"]]
        }
      ],
      "detail_agg": [["fold", "10.0%", "-1.00"]]
    }
  ]
}

v2 Shape

In v2, each top-level hand entry is the same 169-matrix cell, but the field is named handName. Concrete two-card combos are available under combos[].

{
  "hands": [
    {
      "handName": "AKs",
      "strategy": [0.1, 0.2],
      "reach": 1.0,
      "ev": 0.4,
      "actions": [
        { "actionName": "fold", "probability": 0.1, "ev": -1.0 }
      ],
      "combos": [
        {
          "combo": "AsKs",
          "reach": 1.0,
          "actions": [
            { "actionName": "fold", "probability": 0.1, "ev": -1.0 }
          ]
        }
      ]
    }
  ]
}

Field Mapping

v2-Only Fields

These fields exist on the NLHE v2 strategy_grid response and were not part of the legacy v1 strategy_grid contract.

Top-Level Fields

tableState

tableState is new structured state for UI consumers. Important fields:

Each tableState.players[] entry includes:

{
  "position": "BB",
  "stack": 9900,
  "startStack": 10000,
  "committed": 100,
  "folded": false,
  "allIn": false
}

tableState.actingContext includes:

{
  "streetStartPotBb": 1.5,
  "potBeforeBb": 2.5,
  "callFacingBb": 1.0,
  "streetSpentBb": 1.0
}

actionLabels

actionLabels[] is new action metadata for matching model slots to UI actions. This is used by top-row frontend rangeviewer v2 to display aggregated actions for current game state. Each entry can include:

actionHistory

actionHistory[] is new structured history for rendering and replay. Betting entries include position and pot context; deal entries use isDeal: true.

Common fields:

hands[] Additions

The hands[] entries are the replacement for v1 strategy[], but v2 also adds fields that are easier to consume directly:

Each hand.actions[] and combo.actions[] entry uses:

{
  "actionName": "raise7.5",
  "probability": 0.42,
  "ev": 1.25
}

Compared with v1, actionName, probability, and ev are object fields rather than positional array values. probability is a numeric fraction, not a formatted string percentage.

When NLHE v2 request-profile post-processing is enabled, each combo.actions[] entry may also include:

PLO-only fields such as ploBucketTree, ploBucketMap, ploStrategy, ploReach, taxonomyOnly, sampledMode, and holeCardCount are intentionally excluded from this NLHE migration note and will be documented separately.

Migration Notes

Client code that iterates range-matrix entries should switch from:

for (const entry of response.strategy) {
  const hand = entry.combo;
}

to:

for (const hand of response.hands) {
  const handName = hand.handName;
}

Client code that opens a matrix cell and reads the concrete combo breakdown should switch from:

const rows = entry.detail.map((item) => ({
  combo: item.combo,
  reach: item.reach,
  actions: item.detail,
}));

to:

const rows = hand.combos.map((combo) => ({
  combo: combo.combo,
  reach: combo.reach,
  actions: combo.actions,
}));

v2 probabilities are numeric fractions, not formatted percentage strings. Convert only at display boundaries:

const pctText = `${(action.probability * 100).toFixed(1)}%`;
const evText = action.ev.toFixed(2);

Request Migration

To use the v2 holdem strategy_grid path, send a strategy-act-style hand request with:

{
  "protocol_ver": "v2",
  "hand": {
    "game_type": "nlhe",
    "players": [],
    "actions": { "entries": [] }
  }
}

For rangeviewer requests, leave player hole_cards empty. The backend iterates all NLHE two-card combos.

The /strategy_grid route selects the v2 holdem pipeline when protocol_ver starts with v2.

Behavioral Notes

v2 may emit all 169 top-level hands cells, even when a cell has no live concrete combos after board-card blocking. If old code expects only populated cells, filter with:

const liveHands = response.hands.filter((hand) => hand.combos.length > 0);

The default v2 overall strategy is available as overallStrategy. The response also includes gridWeightType, which is uniform by default or reach when requested through grid_weight_type: "reach" or gridWeightType: "reach".