Update README.md

README.md

@@ -1,79 +1,212 @@
 ---
-library_name: transformers
 license: apache-2.0
-pipeline_tag: text-generation
+library_name: transformers
+pipeline_tag: image-text-to-text
+language:
+  - en
 tags:
-- code-translation
-- sas
-- r
-- python
+  - code
+  - code-translation
+  - sas
+  - r
+  - python
+  - lora
+  - axolotl
+  - mistral3
 ---
 
-# Euclid-2.6 — checkpoint-368 merged
+# Euclid-2.5
 
-Bidirectional code translation across all 6 directions among **SAS, R, and Python**
-for statistical / data-processing programs.
+Bidirectional SAS ↔ R ↔ Python program translation. A 24B dense code model, LoRA-tuned and merged to standalone BF16 weights.
 
-## Base
+## Model Summary
 
-`mistralai/Devstral-Small-2-24B-Instruct-2512`, dequantized from its native FP8 to BF16 via `weight_scale_inv`
-(280 block-quantized projection tensors), then LoRA fine-tuned and merged.
-
-## Training recipe
+Euclid-2.5 translates complete statistical and data-processing programs across all six directed pairs over {SAS, Python, R}. The training objective is **behavioural equivalence**: given identical inputs, the translated program must compute identical values and bind them to identically-named results.
 
 | | |
 |---|---|
-| Method | LoRA SFT (no full FT, no CPT) |
-| Rank / alpha / dropout | 128 / 256 (= 2r) / 0.05 |
-| Target modules | all 7 linear projections, language model only (739M trainable) |
-| LR / schedule | 1e-4, cosine to 10%, 30-step warmup |
-| Optimizer | AdamW fused, betas (0.9, 0.95), wd 0.01, grad clip 1.0 |
-| Batch | micro 1 x grad-accum 8, seq 8192, sample packing |
-| Loss | completion-only |
-| Epochs | 2 (736 steps); **this artifact = step 368** |
-| Hardware | 1x H100 80GB, ~4h35m |
+| Developer | ProCogia |
+| Method | LoRA SFT (r=128), adapter merged into the weights |
+| Checkpoint | step 368 (1.0 epoch) |
+| Parameters | 24B dense |
+| Hidden / layers / intermediate | 5120 / 40 / 32768 |
+| Attention heads / KV heads / head dim | 32 / 8 / 128 |
+| Tokenizer | Tekken, 131,072 vocab |
+| Context | 256k architectural; trained at 8,192 |
+| Precision | BF16, ~48 GB |
+| License | Apache 2.0 |
+
+**Multimodality.** A vision tower is present in the architecture and untouched by fine-tuning. The model is text-only in practice; the tower carries ~1–2 GB of inert VRAM and dictates the loader class (see [How to Use](#how-to-use)).
+
+## Intended Use
+
+- Single-turn translation of complete programs across the six directed pairs over {SAS, Python, R}.
+- Target environments matching the training distribution: **R** — base R plus `dplyr`; **Python** — `pandas`, `numpy`, `scipy`, `statsmodels`.
+- Output contract: the translated program only, no prose, no markdown fences.
+
+## How to Use
+
+### Loader class
+
+`AutoModelForCausalLM` raises `Unrecognized configuration class`.
+
+```python
+import torch
+from transformers import AutoModelForImageTextToText
+
+model = AutoModelForImageTextToText.from_pretrained(
+    "ProCogia/Euclid-2.5",
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+)
+```
+
+Tokenization must route through `mistral-common` using the bundled `tekken.json`.
 
-## Data
+### vLLM
 
-12,952 examples over 2,603 semantic programs, balanced across all 6 directions
-(each program present in SAS, Python and R). Held-out eval sets are repo-disjoint
-from training.
+```bash
+vllm serve ProCogia/Euclid-2.5 \
+  --tokenizer-mode mistral \
+  --max-model-len 16384
+```
+
+`--tokenizer-mode mistral` is required. Routing through a jinja template instead of `mistral-common` produces systematically degraded output that closely resembles a genuine accuracy result.
+
+### Prompt format
+
+The model was trained against a single system prompt across every row. Deviating from its contract is off-distribution. The exact prompt (MD5 prefix `dc99ebd18483`) ships with the proprietary training data; the block below reproduces its contract:
 
-## Checkpoint selection
+```text
+You are a code translation engine for statistical and data-processing programs written in SAS, Python, and R.
+
+You are given one complete program in a source language and produce the equivalent program in the target language. Behavioural equivalence is the only criterion: given the same inputs, your program must compute the same values and place them in results carrying the same names.
+
+- Preserve the source program's structure, step order, and intent. Carry its comments across as comments in the target language, and add a brief comment where the target expresses a source construct non-obviously.
+- Name every result exactly as the source names it, so results can be compared name for name.
+- SAS semantics decide the answer even when SAS is not the target language. A SAS date is whole days since 1960-01-01 and a datetime is seconds since 1960-01-01, both stored as plain numbers. A SAS FORMAT changes only how a value is displayed, never what is stored. Missing (.) sorts below every number, so `x < 5` is true when x is missing. Character values are blank-padded to a declared length and compare ignoring trailing blanks.
+- A step that only prints or plots produces no data and has no translation outside SAS; leave it out rather than inventing an equivalent.
+- Respond with the translated program and nothing else: no prose, no explanation, no markdown code fences, no placeholders.
+```
 
-Eval loss (n=120) reached its minimum in epoch 1 and rose ~0.08 through epoch 2,
-so the late checkpoints were discarded:
+The user turn is:
 
-| checkpoint | eval loss |
+1. `Translate the following {SOURCE} program to {TARGET}.`
+2. A target-language instruction block (one of three: R, Python, SAS) specifying the permitted library environment.
+3. The source program, fenced with the **source** language tag.
+
+The model emits a bare program. Absence of a ```` ```sas ```` fence is the direct signal that the fine-tuned weights are active — the untuned weights emit markdown fences, these do not.
+
+## Training Data
+
+**Proprietary. Not released.** Composition is disclosed below for reproducibility of method, not of data.
+
+| | |
 |---|---|
-| 184 | 0.5474 |
-| 368 | 0.5487 |
-| 552 | 0.5892 |
-| 736 | 0.6110 |
+| Training rows |**12,952**|
+| In-loop validation | 120|
+| Held-out execution set | 424|
+| Format | JSONL, single-turn `system` + `user` + `assistant` |
+| Length (chars) | mean 6,226 / p50 4,682 / p90 11,690 / p99 21,205 / max 68,627 |
 
-Checkpoints 184 and 368 are statistically indistinguishable on eval loss (0.0013 apart);
-both are published so they can be compared on execution-based functional equivalence.
+Direction balance:
 
-## Evaluation status
+| Direction | Rows | Direction | Rows |
+|---|---|---|---|
+| Python→R | 2,070 | R→SAS | 2,213 |
+| Python→SAS | 2,199 | SAS→Python | 2,199 |
+| R→Python | 2,070 | SAS→R | 2,213 |
 
-Execution-based eval (n=424, repo-disjoint, dataframe-level output comparison)
-**pending**. Eval loss is a token-level proxy and does not measure behavioural
-equivalence, which is this model's only correctness criterion.
+## Training Procedure
 
-## Usage
+### Weight preparation
+
+The starting checkpoint ships in native FP8 (`float8_e4m3fn`, block-quantized) with no official BF16 weights, and FP8 does not support training. Casting via `model.to(torch.bfloat16)` **silently no-ops** on quantized linear layers, writing FP8 bytes labelled BF16.
+
+Weights were dequantized by streaming safetensors shards directly:
 
-```python
-from transformers import AutoTokenizer, AutoModelForCausalLM
-m = AutoModelForCausalLM.from_pretrained("momosushi/Euclid-2.6", dtype="bfloat16", device_map="auto")
 ```
+W_bf16 = W_fp8.to(float32) × expand_blocks(weight_scale_inv)
+```
+
+280 tensors (40 layers × 7 projections) were converted — exactly the modules LoRA attaches to. `activation_scale`, `input_scale`, and `kv_scale` are FP8-runtime only and were discarded. Verification: 280/280 converted, on-disk dtype scan `Counter({'BF16': 585})` with zero `F8_E4M3`, finiteness assertion passed on every parameter, 48.0 GB output, and a live generation coherence check.
+
+### LoRA configuration
+
+| Parameter | Value |
+|---|---|
+| Rank `r` | 128 |
+| `alpha` | 256 (α = 2r → rank-independent scaling factor of 2) |
+| Dropout | 0.05 |
+| Target modules | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` |
+| Scope | Language model only; vision tower and projector excluded |
+| Embeddings / `lm_head` | Frozen |
+| Trainable | 739M (≈3.0%) |
 
-Prompt with the training system prompt (translation contract: output only the
-translated program, no prose, no markdown fences).
+Vision exclusion is structural rather than enumerated: the targeting regex keys on `self_attn|mlp` parent names, which exist only in the language model, while the vision tower uses `attention`/`feed_forward`.
 
-## Adapters and sibling model
+MLP targeting accounts for 78.7% of available per-layer LoRA capacity at hidden 5120 / intermediate 32768; attention-only targeting would forfeit four-fifths of it.
 
-Unmerged LoRA adapters for all four checkpoints:
-`momosushi/Euclid-devstral` branch `checkpoints`.
+### Optimization
 
-This checkpoint's sibling from the same training run:
-`momosushi/Euclid-devstral` (checkpoint-184) and `momosushi/Euclid-2.6` (checkpoint-368).
+| Parameter | Value |
+|---|---|
+| Learning rate | 1e-4, cosine to 10% of peak |
+| Warmup | 30 steps (fixed count, ~4% of 736) |
+| Optimizer | `adamw_torch_fused`, β = (0.9, 0.95), wd 0.01 |
+| Gradient clipping | 1.0 |
+| Micro-batch × accumulation | 1 × 8 (≈36 examples/step) |
+| Sequence length | 8,192, sample packing on, cross-sample masked |
+| Loss | Completion-only |
+| Precision | BF16 + gradient checkpointing, FlashAttention-2 |
+| Epochs | 2, checkpointed every 0.5 |
+| Seed | 42 |
+| Total steps | 736 |
+
+At α=2r, LR 1e-4 is equivalent in effective update magnitude to LR 2e-4 at α=r. Over-length rows were **dropped, never truncated** — 12 rows exceeded 8,192 tokens (0.09%), measured with exact `mistral-common` counts. Truncating an assistant target teaches premature EOS, which is directly harmful on a task whose contract is "the complete program and nothing else."
+
+Six pre-flight gates ran before training: exact token lengths, loss-mask decoding (asserting supervised positions contain only the assistant program), adapter scope and parameter count, packing confirmation, leakage checks, and system-prompt integrity. An adapter weight scan for NaN and residual all-zero `lora_B` tensors was added mid-project and is a required gate for any rerun of this recipe.
+
+### Infrastructure
+
+| | |
+|---|---|
+| GPU | 1× H100 80GB SXM |
+| Framework | Axolotl 0.17.0.dev0, torch 2.10.0+cu128, transformers v5 |
+| Peak VRAM | 71.1 GB training / 60.3 GB eval |
+| Throughput | ~1,150–1,360 tok/s, ~22 s/step |
+
+## Evaluation
+
+**Pending.**
+
+The planned protocol:
+
+| Element | Specification |
+|---|---|
+| Set | 424 examples, repo-disjoint, offline |
+| Method | Execute source and translation on identical inputs; compare at dataframe level |
+| Metric | pass@1, pooled |
+| Prompt | Training system prompt, greedy decoding |
+
+
+## Hardware Requirements
+
+| | |
+|---|---|
+| Weights on disk | ~48 GB (BF16) |
+| KV cache @ 16k context | ~2.6 GB per sequence (40 layers × 8 KV heads × 128 dim) |
+| Inert vision tower | ~1–2 GB |
+| Practical single-GPU floor | 80 GB (H100 / H200 / A100 80GB) |
+| Multi-GPU | 2× 48 GB (L40S, A6000) with tensor parallelism |
+
+## Citation
+
+```bibtex
+@misc{euclid_2_5,
+  title  = {Euclid-2.5: Bidirectional SAS/R/Python Program Translation},
+  author = {ProCogia},
+  year   = {2026},
+  url    = {https://huggingface.co/ProCogia/Euclid-2.5}
+}
+```