Быстрый старт: анализ позиции коротких нард через API

Шаг 1 — получить API-ключ

API анализа сейчас в приватной бете. Запросите доступ через форму на странице для разработчиков — вы получите API-ключ со scope positions.analyze и квотой по rate-limit, достаточной для оценки. Тарифы и лимиты сообщаются при выдаче доступа.

Шаг 2 — закодировать позицию

Соберите JSON-тело с четырьмя ключами: game_type ("narde" или "backgammon"), position, decision и context.

Объект position специфичен для игры. Для длинных нард это {"pips": [...]} — массив из 24 знаковых целых, индексируемый по игровому пипу (индекс i = пункт i+1). Положительные значения — шашки белых (X), отрицательные — чёрных (O). Стандартная стартовая позиция: 15 белых на игровом пипе 24 (индекс 23), 15 чёрных на игровом пипе 12 (индекс 11). Для коротких нард форма та же.

{
  "game_type": "narde",
  "position": {
    "pips": [
       0,  0,  0, -1, -1,  1,
      -2,  1,  1,  1, -1, -8,
       0,  1,  0,  0,  0,  0,
       1, -1,  0, -1,  0,  9
    ]
  },
  "decision": {
    "type": "checker_play",
    "dice": [4, 2],
    "played": [
      { "from": 14, "to": 10 },
      { "from": 10, "to": 8 }
    ]
  },
  "context": {
    "player": "x",
    "match_state": null
  }
}

Для checker-play played — это последовательность ходов, выбранная игроком. API возвращает ранжированные альтернативы, чтобы вы могли сравнить сыгранную последовательность с топом движка. Для cube-решений замените объект checker_play на {"type": "cube_decision", "offer_made": true, "response": "take"}.

Шаг 3 — отправить curl-запрос

POST-ните тело на /api/v1/positions/analyze с bearer-аутентификацией:

curl -X POST https://nardex.ai/api/v1/positions/analyze \
  -H "Authorization: Bearer $NARDEX_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

JWT-вызовы (браузерный SDK, авторизованные дашборды) пропускают заголовок Bearer — авторизацией служит сама сессия. API-key-вызовы обязаны иметь scope positions.analyze; иначе сервер вернёт 403.

Шаг 4 — интерпретировать ответ

Ответ — это объект PositionAnalysis:

{
  "alternatives": [
    {
      "play": [{ "from": 14, "to": 10 }, { "from": 10, "to": 8 }],
      "equity": 0.494,
      "probabilities": {
        "win": 0.700,
        "win_m": 0.258,
        "win_k": 0.062,
        "lose_m": 0.123,
        "lose_k": 0.029
      }
    }
  ],
  "chosen": null,
  "equity_loss": 0.0,
  "grade": "ok",
  "equity_kind": "money",
  "forced": false,
  "analysis_depth": "ply_zero"
}

• alternatives — топ-N ходов-кандидатов, отсортированы по equity по убыванию. У каждого есть play, equity и сырой вектор probabilities (win / win_m / win_k / lose_m / lose_k для длинных нард — это вложенные ординальные вероятности, а не 6-классовый softmax).
• chosen — альтернатива, которую игрок реально сыграл, если она не вошла в топ-N. null, если выбранный ход уже есть в списке.
• equity_loss — best.equity − chosen.equity (≥ 0). То, что игрок «оставил на столе», не выбрав топовый ход движка.
• grade — четырёхуровневая метка (в духе XG/GnuBG): ok, doubtful, error, blunder. Пороги бакетов живут на сервере и калибруются по типу игры.
• equity_kind — на какой шкале посчитан equity_loss. Значения с разными equity_kind нельзя усреднять вместе:
  • money — сырое money-эквити — ходовые (checker-play) решения money-игры.
  • match — money-эквити, отмасштабированное под матч, когда в запросе был передан match_state (альтернативы оцениваются в MWC, а не в сырой equity); тоже ходовые решения.
  • match_emg — кубовое решение, оценённое по реальной таблице матч-эквити (MET): потеря в EMG-единицах (money-эквивалент). Это единственная кубовая шкала, которую можно усреднять с ходовыми потерями.
  • cube_dist — кубовое решение с константными порогами — путь, по которому сервер идёт, когда MET недоступна (met_based: false). Это НЕ потеря эквити, а расстояние 2·|win_prob − порог|: на заведомо выигранной позиции оно доходит до ~3.0, на порядок больше типичной EMG-потери.
• forced — true, если был только один легальный ход (автоматически исключается из расчёта PR / blunder-rate).
• analysis_depth — сейчас всегда "ply_zero"; более глубокий поиск ("ply_two", "ply_three") в roadmap.

Шаг 5 — следующие шаги

Round-trip работает — теперь решите, как встраивать Nardex в свой продукт:

• Сравните Nardex с gnubg и XG на странице сравнения — какой движок подходит вашей платформе и лицензионной модели.
• Кэшируйте запросы у себя. Сервер уже мемоизирует по (position, decision, context, depth), но пропуск сетевого round-trip-а экономит реальную latency на горячих путях.
• Обрабатывайте 429 (rate limit) экспоненциальным back-off-ом. Самая частая причина — burst evaluation-вызовов во время импорта матчей. Следите также за 403 — он означает, что у ключа нет scope positions.analyze.
• Перейдите на JWT-аутентификацию, когда встраиваете Nardex в браузерный дашборд — уберите API-ключ из клиентского кода; сессии пользователя достаточно.