Agent players

Bots and LLM agents play through one-shot shell commands. The run is saved to a state file between calls, and every reply is JSON (observation schema 3).

python -m chaos_blackjack.agent new --seed 7 --chaos
python -m chaos_blackjack.agent --brief bet 10
python -m chaos_blackjack.agent --brief act hit

The loop

Read obs.hint and obs.legal_actions.
Send exactly one legal action.
Read events (what just happened) and the new obs.
Repeat until obs.phase is run_over.

Observations contain only what a player at the table can see. Do not decode the state file.

Commands

Command	Meaning
`act`	act in your turn
`bet`	place a bet
`buy`	buy a shop item (betting phase)
`cancel`	drop the pending question when it allows it
`choose`	answer the pending question (obs.choice)
`help`	list game commands
`new`	start a new run (overwrites the run file)
`observe`	show the current observation
`perform`	run one of the table's own actions (obs.table_actions)
`play`	streaming JSON-lines mode on stdin/stdout
`reroll`	roll the shop's stock again (betting phase, once per stock)

Actions

Action	Meaning
`bet`	start the round: bet <amount>
`buy`	buy a shop offer before betting: buy <item_id> (see obs.shop; some ask obs.choice next)
`cancel`	drop the pending question; nothing is charged or spent
`choose`	answer the pending question: choose <option id> (see obs.choice)
`double`	double the bet, take exactly one card, then stand
`hit`	take one more card
`perform`	run one of obs.table_actions: perform <action> [arg]
`reroll`	roll the shop's stock again (obs.shop.reroll_price chips)
`stand`	end your turn; the dealer plays
`surrender`	give up the hand and get part of the bet back
`use_item`	use an item whose usable is true: act use_item <item_id> [--target <id>]

Errors

A rejected command changes nothing; read error.legal_actions and retry.

Error code	Meaning
`illegal_action`	Not allowed right now (wrong phase, bet out of range, item you don't own).
`invalid_argument`	Missing or malformed argument.
`invalid_json`	Streaming mode: the line is not valid JSON.
`run_over`	The run has ended; start a new one.
`step_limit`	The step limit was reached; start a new run.
`unknown_command`	Unknown command.
`usage`	No or invalid run file, or bad command-line usage (exit code 2).

A recorded run

This run is replayed on every wiki update with seed 7, chaos on, a flat bet and a "hit below 17" policy. If the game changes, this table changes with it.

python -m chaos_blackjack.agent new --seed 7 --chaos

Step	You send	Events	Table after
1	`bet 10`	Round 1 started, bet 10	Round 1. Bankroll 100/300. Bet 10. You: 8♣ 3♥ = 11. Dealer: K♣ ?? = ?.
2	`act hit`	You draw: Q	Round 1. Bankroll 100/300. Bet 10. You: 8♣ 3♥ Q♥ = 21. Dealer: K♣ ?? = ?.
3	`act stand`	Dealer draws: 8 Dealer busts.	Round 2. Bankroll 110/300. Shop: swap 1, hole_card_hacker 2, danger_radar 3 (restocks in 1 round; reroll 3). player +10
4	`bet 10`	Round 2 started, bet 10 ⚡ Chaos effect applied: Odd Even Chaos	Round 2. Bankroll 110/300. Bet 10. You: 6♥ Q♦ = 18. Dealer: A♦ ?? = ?. Active chaos rules: Odd-Even Chaos: 2/4/6/8 +2, 3/5/7/9 -1; A/10/J/Q/K unchanged (until cleared).
5	`act stand`	Dealer stands at 17. The shop has new stock.	Round 3. Bankroll 120/300. Shop: hole_card_hacker 2, peek 2, shield 4 (restocks in 2 rounds; reroll 3). player +10
6	`bet 10`	Round 3 started, bet 10 ⚡ Chaos effect applied: Fragile Bust	Round 3. Bankroll 120/300. Bet 10. You: J♠ 4♠ = 14. Dealer: K♥ ?? = ?. Active chaos rules: Fragile Table: bust threshold reduced to 19 (instead of 21).
7	`act hit`	You draw: 5	Round 3. Bankroll 120/300. Bet 10. You: J♠ 4♠ 5♠ = 19. Dealer: K♥ ?? = ?. Active chaos rules: Fragile Table: bust threshold reduced to 19 (instead of 21).
8	`act stand`	Dealer stands at 18.	Round 4. Bankroll 130/300. Shop: hole_card_hacker 2, peek 2, shield 4 (restocks in 1 round; reroll 3). player +10

The full guide (observation fields, streaming mode, Python API) is docs/AGENT_GUIDE.md in the game repository.

Current Table modes

Use python -m chaos_blackjack.agent new --mode chaos --seed 7 for Poker Head builds, or --mode j54 for J-54's Table. At J-54 the firmware pick and the Cut target arrive as obs.choice (kinds firmware and cut_target), the deck operations as obs.table_actions (perform j54_cut <group>, perform j54_hot_purge, perform j54_release), and obs.table.public carries compute, the condition, the Joker's state, the meter, the heat map and the bounty. Read obs.choice.options and answer with choose <option> before other moves. Product use may require --target ID; table actions use perform <action> [arg]. obs.table.public exposes build, cash, invested principal, debt, net assets and contracts without private card order or stock outcomes. Legacy --chaos remains a different compatibility path.