Hugging Face's logo

nima1
/
decisioncraft-kai-0.6b

Text Classification
Safetensors
English
decision-model
developer-tools
synthetic-data
custom-code
lora
Model card Files
xet
 Community
decisioncraft-kai-0.6b / docs /tutorials /07-release.md
nima1's picture
nima1
Release reviewed synthetic Decisioncraft study and reproducible artifacts
4485193 verified
preview code
|
Raw History Blame Contribute Delete
10 kB

M6 — Package and verify an installed release

A checkpoint is useful only if someone else can load the intended weights with the intended prompt and routing policy. This milestone packages those pieces, checks their identities before importing Kai's custom runtime, and verifies a wheel installation outside the development checkout.

Evidence at packaging time: the local installed wheel reproduced all six saved validation logits exactly on CUDA and routed a request from /tmp. Public upload, anonymous download and fresh-cache reload follow sealing. Consult the publication record for the actual immutable revisions and download-check results; this source archive preserves the instructions as packaged. The local checks establish package portability, not public availability.

What is being released

The selected model is kai-adapted-s42: LoRA plus decision-head updates trained on the 1,008-row training partition, using the compact prompt and seed 42. Selection occurred on validation before calibration and final scoring. The frozen protocol supplies the routing policy. See the final study for measured performance and the separate demonstration's confident error.

Publish the small adaptation, runtime settings, policy, six validation references, license notices and exact file hashes. Download the unchanged Kai package separately at its pinned revision. This avoids repeatedly distributing the base weights and makes the boundary between upstream weights and project updates explicit. A LoRA checkpoint must be loaded against the same original base; a generic adapter loader with an arbitrary base is insufficient.

The development repository is private. Public users therefore also need the wheel, locked source archive, tutorials, final report and lightweight evidence archive. They can audit saved predictions without the private repository or unselected checkpoints. Full retraining follows the earlier tutorials and requires new model downloads and experiments.

1. Build the wheel and public files

Run these commands from the reviewed repository after committing the files intended for publication. The staging helper uses git ls-files: an untracked new tutorial or script will not enter the source archive.

uv build --wheel
uv run --locked --extra ml python scripts/stage_public.py \
  --output artifacts/public-reproduction

Use a new output directory for every attempt. Staging makes three distributions:

  • decisioncraft-source.tar.gz: reviewed code, configuration, authored data specifications, tutorials, tests, compact reports and dependency lockfile.
  • decisioncraft-evidence.tar.gz: original prediction bytes, final analysis and lightweight historical run records. It excludes unselected weight checkpoints.
  • dataset/: the four frozen partitions and manifest, labeling policy, review records, authored specifications and source archive.

The source and evidence archives extract to separate sibling directories. The public audit instructions show their exact layout. Private Git history, environments, caches, authentication state and development planning files are excluded. Review the staged inventory before publication; staging is not an upload.

2. Seal the selected adaptation

The builder verifies the selected completed run, its checkpoint bytes, original base identity, runtime configuration, dataset identity and frozen protocol before creating a new release directory. The six reload references come from validation, not final-test cases.

uv run --locked --extra ml python scripts/seal_public.py \
  --staged artifacts/public-reproduction \
  --wheel dist/decisioncraft-0.1.0-py3-none-any.whl \
  --output artifacts/model-release-reproduction
uv run --locked --extra ml decisioncraft verify-release \
  --release artifacts/model-release-reproduction

verify-release verifies the exact inventory without loading a model. Adding a README or replacing the wheel after sealing changes the inventory and invalidates verification. Complete the content first, then build a new release instead of editing a sealed directory. The sealing wrapper includes all staged documentation, reports and configurations, with private development links removed by staging. The lower-level scripts/build_release.py also accepts repeated --asset RELATIVE_NAME=FILE arguments for an explicitly reviewed custom inventory.

The public source archive intentionally lacks the selected training-run directory. Rebuilding the adaptation from source requires a full rerun of training. Consumers of the existing release use its sealed adaptation directly.

3. Install the wheel into its own environment

For a reproducible local installation, use the source project's lockfile to resolve dependencies and install the built wheel separately. The source configuration preserves the explicit PyTorch CUDA index mapping.

release_env="$PWD/artifacts/installed-reproduction-env"
UV_PROJECT_ENVIRONMENT="$release_env" uv sync \
  --locked --extra ml --no-dev --no-install-project
uv pip install --python "$release_env/bin/python" --no-deps \
  dist/decisioncraft-0.1.0-py3-none-any.whl

--no-install-project prevents an editable source installation from masquerading as a wheel test. --no-deps on the wheel installation keeps the already locked dependency environment intact. This environment is separate from the development .venv.

The actual local check used artifacts/installed-env with Python 3.13 and the committed ML dependencies. An earlier exported-requirements installation failed on a Triton index/hash mismatch. Its log is retained at artifacts/release-install.stderr. The successful recovery used the locked project and its explicit index configuration; no hash check was disabled.

4. Check the installed runtime outside the checkout

Use absolute release and base paths so inference does not depend on the current working directory:

release_dir="$PWD/artifacts/model-release-reproduction"
base_dir="$PWD/artifacts/kai-package"
cd /tmp
"$release_env/bin/decisioncraft" check-release \
  --release "$release_dir" --base "$base_dir" --device cuda:0
"$release_env/bin/decisioncraft" predict \
  --release "$release_dir" --base "$base_dir" --device cuda:0 \
  --request 'List the entries here.' \
  --context 'Current directory is /workspace/manuals.'

check-release compares the six stored validation references using the reviewed inference settings. The verified local result in artifacts/installed-reference.json had passed: true and maximum absolute logit difference 0.0. This used the sealed local demonstration package at artifacts/m5-demo-release and the already downloaded original base. It is a fresh environment test, not a fresh model-download test.

The installed request in artifacts/installed-predict.json returned suggest, calibrated probabilities, the fitted policy and a suggestion_request handoff. Both command-generation and command-execution fields were false. The runtime neither lists the directory nor calls Bashcraft. The returned text asks the caller to pass the original request/context to a generator and review its output.

CUDA uses FP32 model parameters with BF16 autocast, matching the reviewed study settings. CPU FP32 inference is implemented, but the CUDA checks do not establish CPU numerical parity or speed. Do not turn a CPU mismatch into a passing result by silently relaxing tolerances.

5. Publish and verify a fresh download

Publication targets are public nima1/decisioncraft-kai-0.6b and nima1/decisioncraft-data; the GitHub development repository remains private. Upload only the reviewed sealed directories. Record the full returned commit revisions, verify anonymous access and download those exact revisions into new output directories and new Hugging Face caches.

After obtaining the actual immutable model revision, the installed CLI supports:

export HF_HOME="/absolute/path/to/new-hf-cache"
export HF_HUB_CACHE="$HF_HOME/hub"
"$release_env/bin/decisioncraft" download-release \
  --repo nima1/decisioncraft-kai-0.6b \
  --revision FULL_MODEL_COMMIT_FROM_THE_RELEASE_RECORD \
  --output /absolute/path/to/new-downloaded-release
"$release_env/bin/decisioncraft" download-base \
  --release /absolute/path/to/new-downloaded-release \
  --output /absolute/path/to/new-downloaded-base

The revision placeholder is deliberate: the source archive is sealed before publication supplies its immutable revision. The downloader requires a full immutable identity, not main. Setting only a new output directory may still reuse the global Hub cache; explicit fresh cache paths are necessary to substantiate a fresh download.

Install the downloaded wheel into another fresh environment using the downloaded source archive's pyproject.toml and uv.lock, then repeat check-release and the installed prediction with the downloaded paths. Run the CPU public evidence audit against the downloaded dataset and evidence archives. Record the first output and any failure rather than replacing failed evidence.

Troubleshooting and acceptance

A release/base hash mismatch means the files differ from the sealed identities; retrieve the matching immutable artifacts. An existing output-directory error requires a new destination. Low free GPU memory requires waiting for capacity, not stopping another workload. Upstream tokenizer warnings were observed in the study; changing tokenizer settings after the reference freeze changes the tested runtime.

The public download, six-reference comparison, installed prediction and saved-output audit each answer a different question. Milestone M6 is complete only after the published artifacts pass all of them and their immutable revisions are recorded. A successful package check does not erase the synthetic-data limitations or the confident failure documented in the final report.