LLM

Provider-independent prompt building and reply parsing for LLM agents.

MAX_NOTES_LENGTH module-attribute

MAX_NOTES_LENGTH: Final = 200

Maximum number of characters kept from an agent's notes.

SYSTEM_PROMPT module-attribute

SYSTEM_PROMPT: Final[str] = RULES + '\n' + RESPONSE_FORMAT

The rules and the reply format, the same for every game and every player.

build_prompt

build_prompt(
    state: GameState,
    viewer_uid: int,
    valid_actions: tuple[Action, ...],
    notes: str | None = None,
) -> str

Returns the viewer's rendered state, their notes if any, then their numbered options.

Parameters:

Name	Type	Description	Default
state	GameState	The game state; it is scrubbed for the viewer first.	required
viewer_uid	int	UID of the player being prompted.	required
valid_actions	tuple[Action, ...]	The actions the player may take now.	required
notes	str | None	The player's private notes, shown only when not empty.	None

Returns:

Type	Description
str	The user message for this turn.

parse_action

parse_action(
    response: str, valid_actions: tuple[Action, ...]
) -> Action

Returns the offered action chosen by the last JSON object in an LLM reply.

Parameters:

Name	Type	Description	Default
response	str	The model's reply.	required
valid_actions	tuple[Action, ...]	The actions offered in the prompt, in the same order.	required

Returns:

Type	Description
Action	The chosen action, with message filled in for a SpeakAction.

Raises:

Type	Description
InvalidMoveError	If the reply has no usable choice, the number is not a valid option, or a speech has no message.

parse_notes

parse_notes(response: str) -> str | None

Returns the cleaned notes from the last JSON object in an LLM reply, or None if it has none.

Parameters:

Name	Type	Description	Default
response	str	The model's reply.	required

Returns:

Type	Description
str | None	The notes with whitespace collapsed and cut to MAX_NOTES_LENGTH characters, or None.

Raises:

Type	Description
InvalidMoveError	If the reply has no JSON object with an action key.

An agent that plays through litellm; it needs the llm extra.

LLMAgent

An agent that plays through any model litellm supports.

Each turn it sends SYSTEM_PROMPT as the system message and build_prompt as the user message, then reads the reply with parse_action and parse_notes. When a reply is rejected, the next call adds that reply and the reason to the conversation.

Attributes:

Name	Type	Description
uid		The player's unique ID.
model		The litellm model string.
completion_kwargs		Extra arguments for litellm.acompletion.
notes		Private notes, shown back to the agent on each of its turns.
prompt_tokens		Total prompt tokens used.
completion_tokens		Total completion tokens used.
cached_tokens		Total prompt tokens read from the provider's cache.
cost		Total cost in US dollars, from litellm.completion_cost.

__init__

__init__(
    uid: int,
    model: str,
    completion_kwargs: frozendict = frozendict(),
)

Creates the agent.

Parameters:

Name	Type	Description	Default
uid	int	The player's unique ID.	required
model	str	A litellm model string, such as anthropic/claude-haiku-5-5.	required
completion_kwargs	frozendict	Extra arguments for litellm.acompletion, such as temperature.	frozendict()

choose_action async

choose_action(
    state: GameState, valid_actions: tuple[Action, ...]
) -> Action

Asks the model for an action and updates the notes from its reply.

Parameters:

Name	Type	Description	Default
state	GameState	The game state, scrubbed for this agent.	required
valid_actions	tuple[Action, ...]	The actions this agent may take now.	required

Returns:

Type	Description
Action	The offered action the model chose.

Raises:

Type	Description
InvalidMoveError	If the reply has no usable choice.