# Kuku Yalanji v24.3 Runtime Bundle

**Version:** `v24.3-joint-lexeme-dose29-s3598-20260715`  
**Direction:** English (`eng_Latn`) to Kuku Yalanji (`gvn_Latn`)  
**Runtime status:** load-tested on NVIDIA RTX A6000 and MobTranslate's CPU host  
**Scientific status:** one-seed development candidate; not speaker-certified; not approved for authoritative translation

This release adds explicit `<lexeme>` reconstruction training while retaining the non-Bible sentence treatment.
It has two distinct interfaces:

| Task | Input | What has been measured |
|---|---|---|
| Lexical reconstruction | `<lexeme> woman` | 2,696/2,724 accepted-reference exact on the training-overlapping governed census |
| Sentence translation | `<translate> The woman saw the water.` | Development retention diagnostics only; no free-form reliability claim |

The 98.97% result is deliberate closed-set reconstruction of dictionary records shown during training. It is not
unseen-word generalisation and must not be advertised as 98.97% sentence-translation accuracy.

## Files

- `adapter/`: PEFT 0.19.1 LoRA adapter plus the exact tokenizer with `<lexeme>` at ID 256205.
- `base/`: present only in the complete bundle; exact v21.2 merged model required by this adapter.
- `serve_v2_infer.py`: small reference HTTP server supporting `translate` and `lexeme` tasks.
- `HOSTING-MANIFEST.json`: immutable identities, recipes, evaluation boundaries, and resource measurements.
- `evaluation/`: selected checkpoint decision, run contract, score summaries, and all 28 governed-census failures.

## Install

```bash
python -m venv .venv
. .venv/bin/activate
pip install \
  'torch>=2.4' \
  'transformers>=4.46,<4.49' \
  'peft==0.19.1' \
  'accelerate==1.14.0' \
  'sentencepiece>=0.2,<1'
```

For the adapter-only archive, place the exact v21.2 merged base at `./base`. Do not substitute stock
`facebook/nllb-200-distilled-1.3B`: v24.3 is a continuation of the project-specific v21.2 merged weights.

## Load

```python
import torch
from peft import PeftModel
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

dtype = torch.float16 if torch.cuda.is_available() else torch.float32
tokenizer = AutoTokenizer.from_pretrained(
    "./adapter", src_lang="eng_Latn", tgt_lang="gvn_Latn"
)
base = AutoModelForSeq2SeqLM.from_pretrained("./base", torch_dtype=dtype)
if base.get_input_embeddings().num_embeddings != len(tokenizer):
    base.resize_token_embeddings(len(tokenizer))
model = PeftModel.from_pretrained(base, "./adapter", is_trainable=False)
model.to(device="cuda" if torch.cuda.is_available() else "cpu", dtype=dtype)
model.eval()
```

The resize is required because the adapter tokenizer adds `<lexeme>` after the v21.2 base vocabulary. The final
`.to(dtype=...)` is also required: saved selective-token rows can otherwise retain a different dtype and fail in
the output projection.

## Serve

```bash
python serve_v2_infer.py \
  --model-dir ./base \
  --adapter-dir ./adapter \
  --adapter-sha256 dd61583a60df2d538989e963e104cb626d78965d300e4e473e9a82ef59c04502 \
  --model-id v24.3-joint-lexeme-dose29-s3598-20260715 \
  --host 127.0.0.1 \
  --port 7955 \
  --dtype float32 \
  --threads 4
```

```bash
curl -fsS http://127.0.0.1:7955/health | jq

curl -fsS -H 'content-type: application/json' \
  --data '{"text":"woman","task":"lexeme"}' \
  http://127.0.0.1:7955/translate | jq

curl -fsS -H 'content-type: application/json' \
  --data '{"text":"The woman saw the water.","task":"translate"}' \
  http://127.0.0.1:7955/translate | jq
```

Expected smoke outputs from the measured CPU runtime are `jalbu` and `Jalbu-ngku bana nyajin.` respectively.
They prove loading and task-prefix compatibility, not general linguistic validity.

## Resource envelope

The dynamic CPU form was measured on an eight-vCPU AVX2-only Haswell virtual host with four Torch threads:

- peak cgroup memory: 8,591,966,208 bytes (8.00 GiB);
- settled process RSS: approximately 7.0-7.2 GiB;
- warm-up generation: 40.5-45.3 seconds after model loading;
- measured single-request latency: 4.9-23.2 seconds under variable shared-disk pressure;
- concurrency: one active generation; queue or shed additional requests.

This CPU path is operationally verified but unsuitable for high-throughput hosting. Prefer a GPU host. A merged
model should also reduce duplicated embedding memory, but only publish one after adapter-versus-merged parity is
checked.

## Rights and claims

The upstream NLLB model is CC BY-NC 4.0 and research-oriented. Project data has source-specific terms. This bundle
is for noncommercial research, evaluation, and explicitly labelled drafts. It is not community-certified, not a
speaker authority, and not suitable for health, legal, ceremonial, emergency, or other high-stakes communication.

See <https://mobtranslate.com/docs/kuku-v24-3-model-guide.html> for the complete training, evaluation, deployment,
multi-adapter, provenance, and reproduction guide.