Publish final Run 2 MLX LoRA adapter

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karnesh Mehra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,155 @@
+---
+base_model: mlx-community/Qwen2.5-Coder-3B-Instruct-4bit
+library_name: mlx
+pipeline_tag: text-generation
+license: mit
+tags:
+  - mlx
+  - mlx-lm
+  - lora
+  - text-generation
+  - markdown
+  - supervised-fine-tuning
+  - apple-silicon
+datasets:
+  - nuprl/MultiPL-E
+  - google-research-datasets/mbpp
+---
+
+# Qwen2.5-Coder-3B Markdown Reliability LoRA (MLX)
+
+This repository contains the final MLX-LM LoRA adapter from a two-stage local
+supervised fine-tuning experiment for strict Markdown structure compliance.
+It is designed for the 4-bit Apple Silicon base model
+[`mlx-community/Qwen2.5-Coder-3B-Instruct-4bit`](https://huggingface.co/mlx-community/Qwen2.5-Coder-3B-Instruct-4bit)
+at revision `3dd939c621c08e5753d5b89f35a2642cd83b98ca`.
+
+On a frozen 240-prompt LatentMD evaluation subset, full structural-contract
+accuracy improved from **8.33%** for the base model to **32.08%** after broad
+Run 1 SFT and **82.50%** after the targeted Run 2 correction.
+
+| Model state | Passed | Full contract pass rate |
+| --- | ---: | ---: |
+| Base model | 20/240 | 8.33% |
+| Run 1 broad SFT | 77/240 | 32.08% |
+| Run 2 targeted booster | 198/240 | **82.50%** |
+
+The full experiment, source code, evaluator, generated-data pipeline, configs,
+and report are available at
+[`karyboy/mlx-markdown-reliability-lora`](https://github.com/karyboy/mlx-markdown-reliability-lora).
+
+## What is included
+
+- `adapters.safetensors`: final iteration-300 Run 2 adapter (about 114 MiB);
+- `adapter_config.json`: complete portable MLX-LM adapter/training metadata;
+- `configs/`: frozen experiment, Run 1, and Run 2 configurations;
+- `results/`: final external metrics, comparison, and training summary.
+
+The Run 2 adapter is **standalone relative to the base model**. Although Run 2
+continued training from Run 1, its saved tensor file contains the complete
+final LoRA state; users do not need to download or stack the Run 1 adapter.
+Paths such as `data`, `config`, and `resume_adapter_file` in
+`adapter_config.json` document the original reproducible training run. The
+MLX-LM inference loader uses the model-shape and LoRA fields and does not need
+those training files.
+
+## Load with MLX-LM
+
+MLX-LM expects an adapter directory on disk, so download this repository first:
+
+```python
+from huggingface_hub import snapshot_download
+from mlx_lm import generate, load
+
+BASE_MODEL = "mlx-community/Qwen2.5-Coder-3B-Instruct-4bit"
+ADAPTER_REPO = "logicless/qwen25-coder-3b-markdown-reliability-lora-mlx"
+
+adapter_dir = snapshot_download(
+    repo_id=ADAPTER_REPO,
+    allow_patterns=["adapter_config.json", "adapters.safetensors"],
+)
+model, tokenizer = load(BASE_MODEL, adapter_path=adapter_dir)
+
+messages = [{
+    "role": "user",
+    "content": (
+        "Write a concise Markdown guide with a title, a numbered list, "
+        "and one fenced Python example. Return the document directly."
+    ),
+}]
+prompt = tokenizer.apply_chat_template(
+    messages,
+    tokenize=False,
+    add_generation_prompt=True,
+)
+response = generate(
+    model,
+    tokenizer,
+    prompt=prompt,
+    max_tokens=800,
+    verbose=False,
+)
+print(response)
+```
+
+Install the tested runtime with:
+
+```zsh
+python -m pip install "mlx-lm[train]==0.31.3" "huggingface_hub==1.31.0"
+```
+
+## Training summary
+
+The model was trained using assistant-only token loss with LoRA modules on all
+36 transformer blocks.
+
+| Setting | Run 1 | Run 2 |
+| --- | ---: | ---: |
+| Examples | 5,000 broad SFT | 600 targeted booster |
+| LoRA rank / scale / dropout | 16 / 32 / 0.05 | 16 / 32 / 0.05 |
+| Learning rate | `1e-5` | `2e-6` |
+| Effective batch size | 8 | 8 |
+| Selected iterations | 500 | 300 |
+| Optimizer updates | 125 | 75 |
+| Trained tokens | 261,123 | 91,031 |
+
+Run 1 improved broad structural behavior but failed all 80 external prompts
+that required an outer four-backtick `markdown` wrapper. Run 2 used short
+targets, exact instruction wording, A2 oversampling, and matched A1/A2 contrast
+pairs. It brought external A2 full-contract accuracy from 0/80 to 63/80 while
+preserving the A1 and A3 controls.
+
+## Evaluation
+
+The same frozen prompts and deterministic generation settings were used for
+the base model and both adapters. Run 2 results by wrapper axis were A1 82.50%,
+A2 78.75%, and A3 86.25%. By content-complexity axis they were B1 95%, B2 90%,
+B3 80%, and B4 65%.
+
+The score is produced by this project's deterministic structural evaluator.
+It checks fence balance, wrapper policy, language-specific code examples, raw
+Markdown source, tables, cited blockquotes, and numbered lists. It is not the
+LatentMD authors' official evaluator and does not assess semantic correctness
+of arbitrary prose or code.
+
+## Training data
+
+The SFT examples are deterministically rendered and programmatically verified
+from task-family-disjoint MBPP and MultiPL-E content plans. The LatentMD prompts
+are evaluation-only and are never used as training targets. See the GitHub
+repository's data attribution and generation scripts for exact source
+revisions, licenses, splits, and leakage checks.
+
+## Limitations
+
+- This adapter targets Markdown structure, not factuality or code correctness.
+- The 240-prompt result is a controlled experiment rather than a comprehensive
+  benchmark of Markdown generation.
+- The local evaluator is project-specific.
+- This adapter is in MLX-LM format for Apple Silicon; other runtimes may require
+  conversion.
+
+## License
+
+The adapter and project code are released under MIT. The original base model
+and source datasets retain their respective licenses.

adapter_config.json

@@ -0,0 +1,45 @@
+{
+  "adapter_path": "adapters/qwen25-coder-3b-markdown-reliability-wrapper-run2",
+  "batch_size": 2,
+  "clear_cache_threshold": 0,
+  "config": "configs/lora_wrapper_booster.yaml",
+  "data": "data/processed/wrapper_booster",
+  "early_stopped": false,
+  "fine_tune_type": "lora",
+  "grad_accumulation_steps": 4,
+  "grad_checkpoint": true,
+  "iters": 300,
+  "learning_rate": 2e-06,
+  "lora_parameters": {
+    "dropout": 0.05,
+    "rank": 16,
+    "scale": 32.0
+  },
+  "lr_schedule": null,
+  "mask_prompt": true,
+  "max_seq_length": 1280,
+  "model": "mlx-community/Qwen2.5-Coder-3B-Instruct-4bit",
+  "model_revision": "3dd939c621c08e5753d5b89f35a2642cd83b98ca",
+  "num_layers": -1,
+  "optimizer": "adam",
+  "optimizer_config": {
+    "adafactor": {},
+    "adam": {},
+    "adamw": {},
+    "muon": {},
+    "sgd": {}
+  },
+  "planned_iters": 300,
+  "project_name": null,
+  "report_to": null,
+  "resume_adapter_file": "adapters/qwen25-coder-3b-markdown-reliability-lora/adapters.safetensors",
+  "save_every": 50,
+  "seed": 20260929,
+  "steps_per_eval": 50,
+  "steps_per_report": 10,
+  "stopped_at_iteration": 300,
+  "test": false,
+  "test_batches": 500,
+  "train": true,
+  "val_batches": -1
+}

adapters.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a892954dbf11822d6f4ab1ef50328b6ade8ca3fad072b8706eb319dfaa27e5d5
+size 119789457