XinranSong/nanojev-blackjack-finite-v2

Finite-deck Blackjack decisions — v2

4,000 distinct controlled game states with five questions each (20,000 questions). The generator supplies the complete remaining rank counts and computes outcome distributions by exact branch enumeration using float64 dynamic programming. These are simulated game states, not recorded casino games.

Rules and targets

• —Draw without replacement from a subset of one standard 52-card deck. Ranks are A,2,...,9,10-value; 10/J/Q/K are combined.
• —The state gives player cards, total, usable ace, dealer upcard and all remaining drawable counts. Visible cards have already been removed.
• —There is no predealt dealer hole card and no peek. The dealer draws after the player stops. Player bust loses immediately.
• —Only hit and stand; rewards win/push/loss = +1/0/-1. No natural-21 bonus, doubling, splitting, surrender or insurance.
• —After the first action, the player follows the expected-reward-optimal policy with updated counts, standing on numerical ties.
• —Train/dev/calibration/test use S17. OOD uses H17 and unseen source compositions.

Questions are best_action, hit_outcome, stand_outcome, hit_win, and stand_win. Event distributions are programmatic_conditional_distribution under the stated rules/continuation, not observed outcomes. best_action is an optimal_action_policy (uniform over tied optimal actions): a value of 1 is NOT a win probability. No softmax(Q) target is used. metadata.action_values stores P(win)-P(loss), and metadata.regret stores max(Q)-Q(action). Only best_action has a compatibility hard label; event labels remain unobserved.

Sampling and splits

Seed 29 constructs 100 distinct parent deck compositions, each containing 32–44 cards before the visible deal. Each has at least two aces, one six and two ten-value cards. Each yields 40 states: 20 soft and 20 hard hands, two or three player cards, totals 12–21, dealer upcard A–10. One anchor per source is player [6,10] versus dealer 10. This is a designed sample, not casino state visitation frequency. There is one wording per state.

metadata.source_group_id hashes the parent composition. All its variations stay in one split; semantic states are deduplicated globally even without the rule identifier. OOD combines new compositions and H17, so it is not a matched experiment isolating the rule effect. The test split has only 10 independent source groups; report uncertainty with that dependence in mind.

Intended use and limitations

For controlled probability estimation and expected-reward decision experiments. Full remaining counts are intentionally disclosed, unlike ordinary casino play. The rules are a restricted Blackjack variant. Float64 enumeration is exhaustive under the specified model, not symbolic arithmetic. The 4,000 rows are not independent real games, and compatibility does not establish downstream performance.

License

Generated records, newly authored code and documentation are offered under the MIT license in LICENSE. The two unchanged NanoJev files retain their upstream MIT notice in vendor/nanojev/LICENSE. No model weights or tokenizer files are included.

Format and loading

The authoritative NanoJev records are blackjack/data/{split}.jsonl. Each line is one state with multiple questions. Original bytes, mappings and empty dictionaries are preserved. Native fields are id, state_id, family_id, split, state, questions, gold, gold_probs, gold_probs_kind, gold_label_kind, and metadata.

For the Hugging Face viewer and datasets, viewer/*.parquet provides one row per native record. Mapping fields are losslessly serialized as questions_json, gold_json, gold_probs_json, gold_probs_kind_json, gold_label_kind_json, and metadata_json. This avoids Arrow empty-struct/schema issues and preserves dictionary keys exactly. These are an alternate representation of the SAME records, not additional training data. source_group_id is also exposed as a convenience column.

import json
from datasets import load_dataset

repo_id = "XinranSong/nanojev-blackjack-finite-v2"
ds = load_dataset(repo_id, split="train")
preview_row = ds[0]
row = {k: preview_row[k] for k in ["id", "state_id", "family_id", "split", "state"]}
for key in ["questions", "gold", "gold_probs", "gold_probs_kind", "gold_label_kind", "metadata"]:
    row[key] = json.loads(preview_row[key + "_json"])

For NanoJev, download the native records directly; no conversion is needed:

from huggingface_hub import snapshot_download
folder = snapshot_download(
    repo_id="XinranSong/nanojev-blackjack-finite-v2", repo_type="dataset",
    allow_patterns=["blackjack/data/*"],
)
print(folder + "/blackjack/data")  # pass this directory to the trainer --input

Using a complete NanoJev checkout and its training dependencies:

python scripts/train_pipeline_decisions.py --input /path/to/blackjack/data --validate-only
python scripts/train_pipeline_decisions.py --input /path/to/blackjack/data \
  --objective gold_distribution --loss ce --max-length 512 --output-dir runs/blackjack_v2

Model input is only `state` and `questions`. Never append `gold`, `gold_probs`, or `metadata` to the prompt. In particular, Trading metadata contains future prices for label auditing. Use only train for parameter training, dev for model selection, calibration for fitting calibration parameters, and keep test/ood for final evaluation. Do not concatenate these splits or treat the viewer as extra data.

Reproduction and validation

Python 3.10+ standard library is sufficient for the generator/adapter. Run from the repository root:

python blackjack/generate_blackjack.py
python vendor/nanojev/train_pipeline_decisions.py --input blackjack/data --validate-only
python verify_release.py

verify_release.py needs pyarrow for lossless preview round-trip checks. requirements-preview.txt lists the versions tested for publication. Generation does not require the preview dependencies. build_preview.py rebuilds the Parquet representation after regenerating native data.

The original v2 package passed 14 regression tests, including numerical checks and Trading future-perturbation/boundary checks. Historical tokenization verification at NanoJev commit 71a513bb0163b5634467842b523ee0c0ed6fb1c7 loaded all questions with the official Qwen3-0.6B tokenizer at max length 512. See verification/token_audit_original.json; this is a historical loader test, not model training. The vendored validator remains pinned to that original commit, with its MIT license.

All 4,000 native records and 20,000 question targets also passed the current upstream reader/validator/objective checks at commit 618cea6d906d54e128360786d12f703fff2b1245 (2026-09-20). This is interface compatibility, not a training-performance result. Publication-specific validation and the upstream contract check are recorded in verification/publication_checks.json. No trained weights or controlled training benchmark are included. An informal mixed-task training attempt was reported to reduce performance on other gaming tasks; run settings, metrics and independent reproduction are unavailable. This is anecdotal feedback, not evidence identifying the cause or establishing that the dataset is universally harmful or beneficial. Evaluate each task independently and tune mixture weights on dev if combining datasets.

This is a community dataset prepared for use with NanoJev, not an official NanoJev release. File hashes are in SHA256SUMS.json (excluding that manifest itself).