Skip to content

New-user README and docs/ guides, release loader fix and 1.0-240M work - #10

Merged
uncoalesced merged 30 commits into
mainfrom
feat/240m-slab-v4
Nov 3, 2026
Merged

uncoalesced merged 30 commits into
mainfrom
feat/240m-slab-v4

Conversation

@uncoalesced

Copy link
Copy Markdown
Owner

Summary

People who wanted to try parentheses-0.9 couldn't find out how from the README, which mostly covered training. This PR rewrites it around a quick setup and adds a docs/ folder. While testing the setup I found why a Bluesky tester got gibberish: the chat script was loading the Hugging Face weights wrong.

Loader bug (scripts/chat.py)

When --checkpoint points at the Hugging Face folder, load_model_and_tokenizer built its config without reading slab_v3 from config.json, then loaded with strict=False. That silently dropped 63 tensors (token shift, write gate, value highway), so every user of the release got number soup. The loader now passes slab_v3 and slab_v4 through and prints a warning if any checkpoint tensor fails to load. After the fix, the model on a GPU gives fluent (if often wrong) English and routes Kannada correctly. requirements.txt also gains safetensors, which this path needs.

Docs

  • README.md: four-step quick setup near the top (clone, install, download the three HF files, run with --device cuda), the CPU-only PyTorch trap, an honest "what it can and can't do yet", and short briefs linking each guide.
  • docs/SETUP.md: legend with a jump-to-your-language table for all nine languages, GPU setup, both weight download routes, per-language sections, every chat option and in-chat command, Python usage, and troubleshooting.
  • docs/ARCHITECTURE.md: a readable explainer of the recurrent model, with figures.
  • docs/ROADMAP.md: 0.9 status, the 1.0-240M sessions (including the Session 4 regression), the data licensing problem, and how to help.
  • docs/DOCUMENTATION.md: moved from the root, with a new "using the code" part ahead of the unchanged math.
  • docs/figures/: the existing diagrams plus four new charts, drawn by scripts/plot_docs_figures.py.

Each guide was drafted, then checked by a separate reviewer against the code, with the documented commands and Python snippets run on a real install.

Also in this branch

This branch carries the existing 1.0-240M work (slab_v4 backbone, Net2WiderNet growth, SFT/DPO builders, session launch scripts and watchdogs, license guard) and a merge of main. .agents/ is no longer tracked: its journal was scrubbed of local paths first and is now in .gitignore.

Known issues, not fixed here

  • Auto language detection sends ordinary Telugu to nit, because two Kolami marker words are common Telugu words. The docs tell people to pass --lang tel.
  • LICENSE-MODEL holds Apache 2.0 text, while the 0.9 weights are CC BY-NC 4.0 on Hugging Face. The README links the CC BY-NC licence directly.
  • The chat banner prints a fixed step number and labels nit as Gondi.

…cher

-MaskFile selects the loss mask (train.mask.notrunc.bin zeroes the 7,943
docs cut at max_seq_len 2048), -WarmupSteps passes --warmup-steps, and
-TrainLog captures train.py output as UTF-8. Defaults keep the old
behaviour, so watchdog_gate_final.py is unaffected. The launcher now logs
[FAIL] on a non-zero train.py exit instead of always reporting success.
Resumes the run paused at step 750 by calling train.py directly from the
I: archive checkpoint, keeping max-steps 2000 and cooldown from 1500 with
no second warmup. launch_sft_130m_v3.ps1's resume path would retarget to
step + Steps and shift the cooldown. Takes and releases GPU.lock and logs
train.py output to out/sft_130m_v3_notrunc.log.
…set DPO margins, tokenizer metadata

- check_eval_contamination: prompt_overlap() (exact, containment, short n-gram) and --dpo-pairs;
  eval_honest_suite replaces the 19 prompts that overlapped DPO pairs and refuses to run on overlap
- free_think: _stream_bpe records sampled <think>/</think>; FreeThinkSession.model_closed_think;
  eval_freethink(_showcase) report it instead of the always-true wrapper flag
- train_dpo_130m_v3: margin/acc/loss over all pairs at start, every --full-eval-every and end,
  written to <out-dir>/pair_eval.json
- train.py: inherit tokenizer metadata on resume; BPE runs without a tokenizer now raise;
  130M SFT launchers pass --tokenizer
…nce dataset & 240M invariants

- scripts/train_dpo_130m_v3.py: fix prompt prefix inversion to canonical [USER, lang_id], aligning Token-Shift (mu-mix) with SFT and adding dynamic Dravidian/English script routing

- scripts/audit_dpo_pairs.py: preference pair auditor checking <think> symmetry, length ratios, and abstention gradients

- scripts/build_dpo_pairs_v2.py: dataset rebuild pipeline producing 900 balanced pairs (81.2% symmetric <think>, 0.98x length ratio, +398 net positive abstention gradient)

- scripts/train_dpo_v2_both.py & eval_dpo_v2_candidates.py: dual candidate training and 5-gate decontaminated evaluation battery

- .agents/ARCHITECTURE.md: add Section 9 codifying 240M non-negotiable architectural mandates (4096 doc packing with alpha_t=0/conv/shift boundary reset, SFT abstention prior mass, and inference scratchpad priming)

- .agents/documentation.md: record DPO v2 campaign and decontaminated scorecard
… 240M SSD

- Document-ID Gated Finite Prefix Sums in Chunked SSD (C=64)

- Prevents NaN from (-inf) - (-inf) in intra-chunk prefix sum differences

- Vectorizes intra-chunk attention, chunk-to-state write, inter-chunk decay, and state-to-chunk read
…(d_0 - m_0)

- Replaces d_0 with d_prev = d_0 - m_0 in Equations (3) and (4) of Section 9.1

- Completely seals t=0 seam boundaries when EOT lands on index C-1 of the previous chunk
…stemic abstention generator & 4096 FFD packer
…e guard, watchdog scripts, and master blueprints
README now opens with a four-step quick setup (clone, install, download
the three Hugging Face files, run chat.py with --device cuda) instead of
training instructions, plus short briefs that link to the new guides.

New docs/:
- SETUP.md: language legend at the top, GPU/CUDA install, both weight
  download routes, per-language setup for all nine languages, chat.py
  options and in-chat commands, Python usage, troubleshooting.
- ARCHITECTURE.md: readable explainer of the recurrent model.
- ROADMAP.md: 0.9 status, 1.0-240M sessions, data licensing, how to help.
- DOCUMENTATION.md: moved from the root; adds a "using the code" part
  ahead of the existing math.
- figures/: existing diagrams plus four new on-brand charts, drawn by
  scripts/plot_docs_figures.py.

fix(chat): the safetensors loader ignored slab_v3 from config.json and
loaded with strict=False, silently dropping 63 tensors (token shift,
write gate, V0 highway). Every user of the Hugging Face release got
gibberish. It now passes slab_v3/slab_v4 through and warns when any
checkpoint tensor fails to load.

requirements.txt: add safetensors, which chat.py needs for the release.

@uncoalesced uncoalesced left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All good

@uncoalesced
uncoalesced merged commit f5ec624 into main Nov 3, 2026
2 checks passed
@uncoalesced uncoalesced changed the title New-user README and docs/ guides, release loader fix, and 1.0-240M work New-user README and docs/ guides, release loader fix and 1.0-240M work Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant