jevrecipes

Recipe catalog / game-action

Choose a game action from JSON

Send game state, player state, and available actions as JSON; receive the original selected action with Jev confidence and probabilities.

Your game already supplies JSON state and actions, and you want Jev to choose an action without formatting descriptions or assigning IDs.

Explore this recipe interactively ยท Source and implementation guide

Use game-action in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { gameAction } from 'jev-recipes/game-action';

const result = await gameAction({
  "gameState": {
    "actionsRemaining": 1,
    "opponentScore": 9
  },
  "playerState": {
    "id": "blue",
    "score": 8,
    "energy": 1
  },
  "legalActions": [
    {
      "id": "collect-points",
      "command": "collect",
      "energyCost": 1,
      "points": 2
    },
    {
      "command": "rest",
      "energyGain": 1,
      "points": 0
    }
  ],
  "rules": "The game ends after this action. Highest score wins; unused energy has no value.",
  "objective": "Finish with more points than the opponent."
});
console.log(result);

Input contract

FieldTypeNeeded
gameStatevalueRequired
playerStatevalueRequired
legalActionsarrayRequired
rulesvalueOptional
objectivevalueOptional
Full input and result schemas
{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "gameState": {
        "description": "The current game information available for this decision."
      },
      "playerState": {
        "description": "Information about the player making this decision."
      },
      "legalActions": {
        "type": "array",
        "items": {},
        "description": "The available actions the player can choose from."
      },
      "rules": {
        "description": "Game rules and explanations of game-specific information."
      },
      "objective": {
        "description": "What the player is trying to accomplish."
      }
    },
    "required": [
      "gameState",
      "playerState",
      "legalActions"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "anyOf": [
      {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "output_tokens": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "input_tokens",
              "output_tokens"
            ],
            "additionalProperties": false
          },
          "selection": {
            "type": "string",
            "description": "The internal Choice label associated with the selected action."
          },
          "action": {
            "description": "The original selected action, preserving any existing game ID."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "The confidence returned by Jev."
          },
          "probabilities": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "description": "Jev's probabilities, keyed by internal Choice label."
          }
        },
        "required": [
          "model",
          "usage",
          "selection",
          "action",
          "confidence",
          "probabilities"
        ],
        "additionalProperties": false
      },
      {
        "type": "null"
      }
    ]
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo game-action.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "selection": "action_0",
  "action": {
    "id": "collect-points",
    "command": "collect",
    "energyCost": 1,
    "points": 2
  },
  "confidence": 0.9,
  "probabilities": {
    "action_0": 0.95,
    "action_1": 0.05
  }
}

Evaluation evidence

Fixture only

No verified live accuracy measurement is available. Evaluate representative cases before using this decision in your workflow.

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

Related recipes