kb5000/cgpn-v2.2

CGPN v2.2 Global Expert

CGPN v2.2 is a constraint-graph policy network for reveal-only Minesweeper play. It combines recurrent boundary-focused attention with a gated global mine-budget expert. The expert applies a bounded residual, so a nearly closed gate cannot override a competent base policy with an unbounded correction.

Files

File	Purpose
model.safetensors	Canonical inference-only weights (113 tensors)
config.json	Architecture and Mineproof protocol configuration
mineproof-cgpn.pt	Optimizer-free checkpoint compatible with the Mineproof FastAPI project
mineproof_agent/	Minimal source snapshot required to instantiate the custom model
inference.py	Stateless inference example
examples/observation.json	Example Mineproof observation v2 payload
training/	Release training configurations
metrics.json	Release-gate results and their scope
SHA256SUMS	Weight-file checksums

Quick start

python -m pip install -r requirements.txt
python inference.py examples/observation.json

The example loads model.safetensors, validates the observation graph, and prints the ranked legal reveal distribution. Production stateful inference should use the Mineproof FastAPI service with a stable session_id and stateful_policy_weight=0.1.

After upload, install the lightweight loader directly from the model repository:

python -m pip install "git+https://huggingface.co/kb5000/cgpn-v2.2"

Then download and instantiate the model through huggingface_hub:

from mineproof_agent.hub import CGPNHubModel, predict

model = CGPNHubModel.from_pretrained(
    "kb5000/cgpn-v2.2",
    map_location="cpu",
)
result = predict(model, observation)

from_pretrained downloads config.json and model.safetensors through the Hugging Face cache. This is a custom PyTorch Hub integration, not a Transformers AutoModel and not a hosted Inference Provider widget.

For the existing service, point the agent checkpoint at mineproof-cgpn.pt:

[agents.cgpn-v2-global-expert]
provider = "python"
factory = "mineproof_agent.agents.cgpn:create_agent"
checkpoint = "path/to/mineproof-cgpn.pt"
use_recurrent_state = true
stateful_policy_weight = 0.1
mine_risk_policy_weight = 0.0

Input and output

Input uses mineproof-agent-observation version 2. Cells are row-major and may be open, covered, flagged, blocked_safe, or outside. The model returns a probability distribution over supplied legal reveal actions. It does not place flags or run a symbolic solver.

Training

• Base policy: supervised pretraining followed by PPO and focus/stateful curriculum.
• Global expert: frozen base network plus three trainable modules: global_budget_encoder, global_gate, and global_delta_head.
• Global-budget labels: generated offline with Mineproof's auditor across early, middle, and late board progress.
• Density curriculum: includes high-density 25%–35% boards.
• Reported/on-policy regressions: P1 and P2 snapshots with rotations and reflections.

Proof results are labels only; neither proof constraints nor hidden mine truth are model inputs at inference time.

Release checks

• 48/48 reported global-budget symmetry snapshots select a proven-safe target.
• P1 on-policy replay: won in 34 actions, zero premature guesses in the release check.
• P2 on-policy replay: won in 36 actions, zero premature guesses in the release check.
• 31/31 software tests passed at export preparation time.
• All 101 parameters shared with the stable v2 base checkpoint were byte-identical after expert training.

These are targeted release gates, not a statistically representative win-rate benchmark. Results on arbitrary sizes, densities, forced-guess boards, and distributions outside training may differ.

Limitations

• Minesweeper can require guesses; this model does not guarantee a win.
• The included example is stateless. Stateful behavior depends on session memory in the service runtime.
• The policy was developed primarily on 9×9 and 16×16 boards and should be evaluated before use on substantially different geometries.
• global_gate_probability is an audit signal, not a calibrated probability that global reasoning is logically necessary.
• This is custom PyTorch code, not a Transformers model and not a Hugging Face Inference Provider endpoint.

License

Apache License 2.0. See LICENSE and NOTICE.