tujia-llm 0.2.0__tar.gz

tujia_llm-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ibaibing
+
+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.

tujia_llm-0.2.0/NOTICE

@@ -0,0 +1,11 @@
+Usage boundaries — tujia-llm
+
+Code in this repository is MIT-licensed (see LICENSE).
+
+Model weights — LoRA adapters and merged or quantized checkpoints — are provided
+for research use only. No rights are granted to the training corpora, the source
+recordings, or their speakers, and none of that material is distributed here.
+
+The base model (Qwen/Qwen3-8B) keeps its own license (Apache-2.0) and must retain
+its attribution wherever these weights or results derived from them are
+redistributed or published.

tujia_llm-0.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: tujia-llm
+Version: 0.2.0
+Summary: Tujia language generation with a LoRA adapter on Qwen3-8B (MLX, Apple Silicon)
+Author: ibaibing
+License: MIT
+Project-URL: Homepage, https://github.com/ibaibing/tujia-llm
+Project-URL: Model (Hugging Face), https://huggingface.co/TujiaNLP/tujia-llm-8b-v0.2
+Project-URL: Model (ModelScope), https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2
+Keywords: tujia,low-resource,language,mlx,lora
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: huggingface_hub>=0.24
+Requires-Dist: mlx-lm>=0.21; sys_platform == "darwin" and platform_machine == "arm64"
+Dynamic: license-file
+
+# tujia-llm
+
+LoRA weights and evaluation for Tujia language generation. First public release: **v0.2** (research preview). v0.1 was internal only.
+
+> **Status: research preview.** Suitable for draft lookup and short-sentence translation, not for
+> authoritative output. Exact word-lookup accuracy is 5.8%; sentence similarity is 0.45.
+> See [evaluation](docs/eval-v0.2.md) for details.
+
+## Model
+
+| Item | Value |
+|---|---|
+| Base model | `Qwen/Qwen3-8B` (base, not instruct); MLX conversion `mlx-community/Qwen3-8B-bf16` |
+| Method | LoRA, rank 16, 16 layers, scale 32, dropout 0.05 |
+| Weight size | 74 MB (`adapters.safetensors`) |
+| Training steps | 35,000 + 12,000 continued |
+| Target variety | Northern Tujia, Longshan standard |
+| License | Research use only; see [NOTICE](NOTICE) |
+
+## Download
+
+| Channel | Location |
+|---|---|
+| ModelScope (MLX) | [TujiaNLP/tujia-llm-8b-v0.2](https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2) |
+| ModelScope (GGUF) | [TujiaNLP/tujia-llm-8b-v0.2-gguf](https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2-gguf) |
+| Hugging Face | [MLX adapter](https://huggingface.co/TujiaNLP/tujia-llm-8b-v0.2); GGUF repo is metadata only |
+| GitHub Releases | `github.com/ibaibing/tujia-llm/releases` → `tujia-llm-8b-v0.2.tar.gz` |
+| PyPI | `pip install tujia-llm` (Apple Silicon) |
+
+## Install
+
+**Requirements:** macOS 13+, Apple Silicon, Python 3.10+.
+
+| Memory | Flag | Download | Notes |
+|---|---|---|---|
+| 32 GB+ | default (`bf16`) | ~15 GB | Reference quality |
+| 16 GB | `--precision 4bit` | ~4.5 GB | Runs, but output degrades visibly (repetition, tone errors) |
+
+```bash
+pip install tujia-llm                          # after the PyPI release
+pip install dist/tujia_llm-0.2.0-py3-none-any.whl   # offline / local wheel
+```
+
+The wheel contains code only. Weights (74 MB) and the base model are downloaded on first run.
+
+## CLI
+
+```bash
+tujia-llm info                                  # backend, precision, memory
+tujia-llm lookup 酒
+tujia-llm translate "大家都过好日子。"
+tujia-llm translate "大家都过好日子，土家人们都相好。" --split
+tujia-llm translate "zɤ³⁵" --to zh
+tujia-llm translate "zɤ³⁵" --to en
+```
+
+Options: `--adapter` (local directory or HF repo id), `--precision auto|bf16|4bit`,
+`--max-tokens`, `--json`.
+
+```bash
+tujia-llm lookup 酒 --adapter /path/to/adapter-dir --json
+```
+
+For development, `python scripts/infer.py` offers the same prompts without installation.
+
+## Windows / CPU (GGUF)
+
+The MLX build is Apple Silicon only. For Windows, Linux, and Intel Macs use the GGUF build
+with llama.cpp or Ollama — see [docs/windows-gguf.md](docs/windows-gguf.md).
+
+| File | Size | Memory |
+|---|---|---|
+| `gguf/tujia-llm-8b-v0.2-Q4_K_M.gguf` | 4.7 GB | 16 GB+ |
+| `gguf/tujia-llm-8b-v0.2-f16.gguf` | 15 GB | 20 GB+ |
+
+```powershell
+ollama create tujia -f gguf/Modelfile
+ollama run tujia "「酒」用土家语怎么说？"
+```
+
+## Capabilities and limits
+
+**Works**
+
+- Chinese word → Tujia form + IPA (reliable for high-frequency words)
+- Chinese short sentence → Tujia sentence (stable up to roughly 8 syllables)
+- Tujia sentence → English
+
+**Does not work**
+
+- Authoritative translation, publication-grade text, legal or medical use
+- Folk songs, ritual language, and other low-resource registers
+- Southern Tujia (Luxi) and non-Longshan varieties such as Baojing
+- Out-of-vocabulary words: there is no refusal mechanism, so the model will invent forms
+
+## Evaluation summary
+
+| Metric | Base | v0.2 |
+|---|---|---|
+| Lexicon 500, first-candidate exact | 0% | 5.8% |
+| Lexicon 500, edit similarity | 0.020* | 0.511 |
+| Single-entry 250, similarity | 0.024* | 0.449 |
+| Sentences 100, similarity (split decoding) | 0.082 | 0.451 |
+| Song lyrics, 12 lines, similarity | — | 0.583 |
+
+\* Base model evaluated on the first 100 items only, so not directly comparable to the full sets.
+
+Full tables, dialect breakdowns, and failure modes: [docs/eval-v0.2.md](docs/eval-v0.2.md).
+
+## Prompt format
+
+The model was trained on four fixed templates. Keep them unchanged at inference time:
+
+```
+「{Chinese word}」用土家语怎么说？
+把这句话翻译成土家语：{Chinese sentence}
+把这句话翻译成汉语：{Tujia sentence}
+把这句话翻译成英语：{Tujia sentence}
+```
+
+Output uses mixed Ye pinyin / IPA notation with superscript tone digits, e.g. `zɤ³⁵`.
+
+## Layout
+
+```
+scripts/infer.py        inference example
+docs/eval-v0.2.md       evaluation report
+release/                release config and upload script
+MODEL_CARD.md           model card
+NOTICE                  usage boundaries
+```
+
+## Citation
+
+```bibtex
+@misc{tujia-llm-v0.1,
+  title  = {tujia-llm: LoRA adapter for Tujia language generation (v0.2)},
+  author = {ibaibing},
+  year   = {2026},
+  note   = {Research preview}
+}
+```

tujia_llm-0.2.0/README.md

@@ -0,0 +1,142 @@
+# tujia-llm
+
+LoRA weights and evaluation for Tujia language generation. First public release: **v0.2** (research preview). v0.1 was internal only.
+
+> **Status: research preview.** Suitable for draft lookup and short-sentence translation, not for
+> authoritative output. Exact word-lookup accuracy is 5.8%; sentence similarity is 0.45.
+> See [evaluation](docs/eval-v0.2.md) for details.
+
+## Model
+
+| Item | Value |
+|---|---|
+| Base model | `Qwen/Qwen3-8B` (base, not instruct); MLX conversion `mlx-community/Qwen3-8B-bf16` |
+| Method | LoRA, rank 16, 16 layers, scale 32, dropout 0.05 |
+| Weight size | 74 MB (`adapters.safetensors`) |
+| Training steps | 35,000 + 12,000 continued |
+| Target variety | Northern Tujia, Longshan standard |
+| License | Research use only; see [NOTICE](NOTICE) |
+
+## Download
+
+| Channel | Location |
+|---|---|
+| ModelScope (MLX) | [TujiaNLP/tujia-llm-8b-v0.2](https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2) |
+| ModelScope (GGUF) | [TujiaNLP/tujia-llm-8b-v0.2-gguf](https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2-gguf) |
+| Hugging Face | [MLX adapter](https://huggingface.co/TujiaNLP/tujia-llm-8b-v0.2); GGUF repo is metadata only |
+| GitHub Releases | `github.com/ibaibing/tujia-llm/releases` → `tujia-llm-8b-v0.2.tar.gz` |
+| PyPI | `pip install tujia-llm` (Apple Silicon) |
+
+## Install
+
+**Requirements:** macOS 13+, Apple Silicon, Python 3.10+.
+
+| Memory | Flag | Download | Notes |
+|---|---|---|---|
+| 32 GB+ | default (`bf16`) | ~15 GB | Reference quality |
+| 16 GB | `--precision 4bit` | ~4.5 GB | Runs, but output degrades visibly (repetition, tone errors) |
+
+```bash
+pip install tujia-llm                          # after the PyPI release
+pip install dist/tujia_llm-0.2.0-py3-none-any.whl   # offline / local wheel
+```
+
+The wheel contains code only. Weights (74 MB) and the base model are downloaded on first run.
+
+## CLI
+
+```bash
+tujia-llm info                                  # backend, precision, memory
+tujia-llm lookup 酒
+tujia-llm translate "大家都过好日子。"
+tujia-llm translate "大家都过好日子，土家人们都相好。" --split
+tujia-llm translate "zɤ³⁵" --to zh
+tujia-llm translate "zɤ³⁵" --to en
+```
+
+Options: `--adapter` (local directory or HF repo id), `--precision auto|bf16|4bit`,
+`--max-tokens`, `--json`.
+
+```bash
+tujia-llm lookup 酒 --adapter /path/to/adapter-dir --json
+```
+
+For development, `python scripts/infer.py` offers the same prompts without installation.
+
+## Windows / CPU (GGUF)
+
+The MLX build is Apple Silicon only. For Windows, Linux, and Intel Macs use the GGUF build
+with llama.cpp or Ollama — see [docs/windows-gguf.md](docs/windows-gguf.md).
+
+| File | Size | Memory |
+|---|---|---|
+| `gguf/tujia-llm-8b-v0.2-Q4_K_M.gguf` | 4.7 GB | 16 GB+ |
+| `gguf/tujia-llm-8b-v0.2-f16.gguf` | 15 GB | 20 GB+ |
+
+```powershell
+ollama create tujia -f gguf/Modelfile
+ollama run tujia "「酒」用土家语怎么说？"
+```
+
+## Capabilities and limits
+
+**Works**
+
+- Chinese word → Tujia form + IPA (reliable for high-frequency words)
+- Chinese short sentence → Tujia sentence (stable up to roughly 8 syllables)
+- Tujia sentence → English
+
+**Does not work**
+
+- Authoritative translation, publication-grade text, legal or medical use
+- Folk songs, ritual language, and other low-resource registers
+- Southern Tujia (Luxi) and non-Longshan varieties such as Baojing
+- Out-of-vocabulary words: there is no refusal mechanism, so the model will invent forms
+
+## Evaluation summary
+
+| Metric | Base | v0.2 |
+|---|---|---|
+| Lexicon 500, first-candidate exact | 0% | 5.8% |
+| Lexicon 500, edit similarity | 0.020* | 0.511 |
+| Single-entry 250, similarity | 0.024* | 0.449 |
+| Sentences 100, similarity (split decoding) | 0.082 | 0.451 |
+| Song lyrics, 12 lines, similarity | — | 0.583 |
+
+\* Base model evaluated on the first 100 items only, so not directly comparable to the full sets.
+
+Full tables, dialect breakdowns, and failure modes: [docs/eval-v0.2.md](docs/eval-v0.2.md).
+
+## Prompt format
+
+The model was trained on four fixed templates. Keep them unchanged at inference time:
+
+```
+「{Chinese word}」用土家语怎么说？
+把这句话翻译成土家语：{Chinese sentence}
+把这句话翻译成汉语：{Tujia sentence}
+把这句话翻译成英语：{Tujia sentence}
+```
+
+Output uses mixed Ye pinyin / IPA notation with superscript tone digits, e.g. `zɤ³⁵`.
+
+## Layout
+
+```
+scripts/infer.py        inference example
+docs/eval-v0.2.md       evaluation report
+release/                release config and upload script
+MODEL_CARD.md           model card
+NOTICE                  usage boundaries
+```
+
+## Citation
+
+```bibtex
+@misc{tujia-llm-v0.1,
+  title  = {tujia-llm: LoRA adapter for Tujia language generation (v0.2)},
+  author = {ibaibing},
+  year   = {2026},
+  note   = {Research preview}
+}
+```

tujia_llm-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tujia-llm"
+version = "0.2.0"
+description = "Tujia language generation with a LoRA adapter on Qwen3-8B (MLX, Apple Silicon)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "ibaibing" }]
+keywords = ["tujia", "low-resource", "language", "mlx", "lora"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS :: MacOS X",
+  "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+  "huggingface_hub>=0.24",
+  "mlx-lm>=0.21; sys_platform == 'darwin' and platform_machine == 'arm64'",
+]
+
+[project.urls]
+Homepage = "https://github.com/ibaibing/tujia-llm"
+"Model (Hugging Face)" = "https://huggingface.co/TujiaNLP/tujia-llm-8b-v0.2"
+"Model (ModelScope)" = "https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2"
+
+[project.scripts]
+tujia-llm = "tujia_llm.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["tujia_llm*"]
+
+[tool.setuptools]
+license-files = ["LICENSE", "NOTICE"]

tujia_llm-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tujia_llm-0.2.0/tujia_llm/__init__.py

@@ -0,0 +1,5 @@
+"""Tujia language generation (research preview)."""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

tujia_llm-0.2.0/tujia_llm/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tujia_llm-0.2.0/tujia_llm/backend_mlx.py

@@ -0,0 +1,47 @@
+"""MLX inference backend."""
+
+import re
+from pathlib import Path
+
+
+class MlxBackend:
+    def __init__(self, base: str, adapter: str, max_tokens: int = 96):
+        from mlx_lm import generate, load
+
+        self._generate = generate
+        self.max_tokens = max_tokens
+        self.model, self.tok = load(base, adapter_path=adapter)
+
+    def ask(self, prompt: str, max_tokens: int | None = None) -> str:
+        messages = [{"role": "user", "content": prompt}]
+        templated = self.tok.apply_chat_template(
+            messages, add_generation_prompt=True, enable_thinking=False
+        )
+        out = self._generate(
+            self.model,
+            self.tok,
+            prompt=templated,
+            max_tokens=max_tokens or self.max_tokens,
+            verbose=False,
+        )
+        return re.sub(r"^.*?</think>", "", out, flags=re.S).strip()
+
+
+def resolve_adapter(spec: str | None, default_repo: str) -> str:
+    """Accept a local directory, a local file, or a Hugging Face repo id.
+
+    Cached snapshots are preferred so repeated runs work offline.
+    """
+    from huggingface_hub import snapshot_download
+
+    if spec:
+        p = Path(spec).expanduser()
+        if p.exists():
+            return str(p)
+
+    repo = spec or default_repo
+    kwargs = dict(repo_id=repo, allow_patterns=["*.safetensors", "*.json"])
+    try:
+        return snapshot_download(local_files_only=True, **kwargs)
+    except Exception:
+        return snapshot_download(**kwargs)

tujia_llm-0.2.0/tujia_llm/cli.py

@@ -0,0 +1,102 @@
+"""Command-line interface."""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+from . import __version__
+from .config import (
+    DEFAULT_REPO,
+    TPL_LOOKUP,
+    TPL_TJ2EN,
+    TPL_TJ2ZH,
+    TPL_ZH2TJ,
+    require_mlx,
+    settings,
+)
+
+
+def _common() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(add_help=False)
+    p.add_argument("--adapter", default=argparse.SUPPRESS,
+                   help="local adapter directory/file, or a Hugging Face repo id")
+    p.add_argument("--precision", choices=["auto", "bf16", "4bit"], default=argparse.SUPPRESS,
+                   help="auto picks bf16 on machines with 32 GB or more")
+    p.add_argument("--max-tokens", type=int, default=argparse.SUPPRESS)
+    p.add_argument("--json", action="store_true", default=argparse.SUPPRESS,
+                   help="machine-readable output")
+    return p
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="tujia-llm",
+        description="Tujia language generation (research preview).",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    common = _common()
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    lk = sub.add_parser("lookup", parents=[common], help="Chinese word to Tujia form")
+    lk.add_argument("word")
+
+    tr = sub.add_parser("translate", parents=[common], help="translate a sentence")
+    tr.add_argument("text")
+    tr.add_argument("--to", choices=["tj", "zh", "en"], default="tj",
+                    help="target language: tj (Tujia), zh (Chinese), en (English)")
+    tr.add_argument("--split", action="store_true",
+                    help="split long Chinese sentences at punctuation before translating")
+
+    sub.add_parser("info", parents=[common], help="show backend and model settings")
+    return p
+
+
+def _split_zh(text: str) -> list[str]:
+    return [x for x in re.split(r"(?<=[，。！？；])", text) if x.strip()]
+
+
+def run(args) -> dict:
+    precision = getattr(args, "precision", "auto")
+    max_tokens = getattr(args, "max_tokens", 96)
+    adapter = getattr(args, "adapter", "") or os.environ.get("TUJIA_LLM_ADAPTER", "")
+
+    cfg = settings(precision, DEFAULT_REPO)
+
+    if args.cmd == "info":
+        return {
+            "version": __version__,
+            "base": cfg.base,
+            "precision": cfg.precision,
+            "ram_gb": cfg.ram_gb,
+            "adapter": adapter or cfg.repo,
+            "platform": f"{sys.platform}/{os.uname().machine}",
+        }
+
+    require_mlx()
+    from .backend_mlx import MlxBackend, resolve_adapter
+
+    backend = MlxBackend(cfg.base, resolve_adapter(adapter or None, cfg.repo),
+                         max_tokens=max_tokens)
+
+    if args.cmd == "lookup":
+        prompt = TPL_LOOKUP.format(zh=args.word)
+        return {"input": args.word, "output": backend.ask(prompt)}
+
+    tpl = {"tj": TPL_ZH2TJ, "zh": TPL_TJ2ZH, "en": TPL_TJ2EN}[args.to]
+    if args.to == "tj" and args.split and len(args.text) > 18:
+        parts = [backend.ask(tpl.format(text=s), 64) for s in _split_zh(args.text)]
+        return {"input": args.text, "output": " ".join(parts), "split": len(parts)}
+
+    return {"input": args.text, "output": backend.ask(tpl.format(text=args.text))}
+
+
+def main(argv=None) -> None:
+    args = build_parser().parse_args(argv)
+    result = run(args)
+    if getattr(args, "json", False):
+        print(json.dumps(result, ensure_ascii=False))
+    else:
+        print(result.get("output", result))

tujia_llm-0.2.0/tujia_llm/config.py

@@ -0,0 +1,65 @@
+"""Configuration and local environment helpers."""
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+
+DEFAULT_REPO = "TujiaNLP/tujia-llm-8b-v0.2"
+BASE_BF16 = "mlx-community/Qwen3-8B-bf16"
+BASE_4BIT = "mlx-community/Qwen3-8B-4bit"
+
+# Prompt templates must match training exactly.
+TPL_LOOKUP = "「{zh}」用土家语怎么说？"
+TPL_ZH2TJ = "把这句话翻译成土家语：{text}"
+TPL_TJ2ZH = "把这句话翻译成汉语：{text}"
+TPL_TJ2EN = "把这句话翻译成英语：{text}"
+
+
+@dataclass
+class Settings:
+    repo: str
+    base: str
+    precision: str
+    ram_gb: float
+
+
+def total_ram_gb() -> float:
+    """Best-effort physical memory size in GiB."""
+    if sys.platform == "darwin":
+        try:
+            out = subprocess.check_output(["sysctl", "-n", "hw.memsize"], text=True)
+            return int(out.strip()) / 2**30
+        except Exception:
+            pass
+    try:
+        pages = os.sysconf("SC_PHYS_PAGES")
+        size = os.sysconf("SC_PAGE_SIZE")
+        return pages * size / 2**30
+    except Exception:
+        return 0.0
+
+
+def pick_precision(requested: str) -> str:
+    if requested in ("bf16", "4bit"):
+        return requested
+    # 8B bf16 needs roughly 16 GB for weights plus KV cache.
+    return "bf16" if total_ram_gb() >= 32 else "4bit"
+
+
+def base_model(precision: str) -> str:
+    return BASE_BF16 if precision == "bf16" else BASE_4BIT
+
+
+def settings(precision: str = "auto", repo: str = DEFAULT_REPO) -> Settings:
+    p = pick_precision(precision)
+    return Settings(repo=repo, base=base_model(p), precision=p, ram_gb=round(total_ram_gb(), 1))
+
+
+def require_mlx() -> None:
+    if sys.platform != "darwin" or os.uname().machine != "arm64":
+        raise SystemExit(
+            "This build requires Apple Silicon (macOS arm64) because the adapter is in MLX "
+            "format. On other platforms, use the GGUF build with llama.cpp or Ollama "
+            "(see the README)."
+        )

tujia_llm-0.2.0/tujia_llm.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: tujia-llm
+Version: 0.2.0
+Summary: Tujia language generation with a LoRA adapter on Qwen3-8B (MLX, Apple Silicon)
+Author: ibaibing
+License: MIT
+Project-URL: Homepage, https://github.com/ibaibing/tujia-llm
+Project-URL: Model (Hugging Face), https://huggingface.co/TujiaNLP/tujia-llm-8b-v0.2
+Project-URL: Model (ModelScope), https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2
+Keywords: tujia,low-resource,language,mlx,lora
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: huggingface_hub>=0.24
+Requires-Dist: mlx-lm>=0.21; sys_platform == "darwin" and platform_machine == "arm64"
+Dynamic: license-file
+
+# tujia-llm
+
+LoRA weights and evaluation for Tujia language generation. First public release: **v0.2** (research preview). v0.1 was internal only.
+
+> **Status: research preview.** Suitable for draft lookup and short-sentence translation, not for
+> authoritative output. Exact word-lookup accuracy is 5.8%; sentence similarity is 0.45.
+> See [evaluation](docs/eval-v0.2.md) for details.
+
+## Model
+
+| Item | Value |
+|---|---|
+| Base model | `Qwen/Qwen3-8B` (base, not instruct); MLX conversion `mlx-community/Qwen3-8B-bf16` |
+| Method | LoRA, rank 16, 16 layers, scale 32, dropout 0.05 |
+| Weight size | 74 MB (`adapters.safetensors`) |
+| Training steps | 35,000 + 12,000 continued |
+| Target variety | Northern Tujia, Longshan standard |
+| License | Research use only; see [NOTICE](NOTICE) |
+
+## Download
+
+| Channel | Location |
+|---|---|
+| ModelScope (MLX) | [TujiaNLP/tujia-llm-8b-v0.2](https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2) |
+| ModelScope (GGUF) | [TujiaNLP/tujia-llm-8b-v0.2-gguf](https://modelscope.cn/models/TujiaNLP/tujia-llm-8b-v0.2-gguf) |
+| Hugging Face | [MLX adapter](https://huggingface.co/TujiaNLP/tujia-llm-8b-v0.2); GGUF repo is metadata only |
+| GitHub Releases | `github.com/ibaibing/tujia-llm/releases` → `tujia-llm-8b-v0.2.tar.gz` |
+| PyPI | `pip install tujia-llm` (Apple Silicon) |
+
+## Install
+
+**Requirements:** macOS 13+, Apple Silicon, Python 3.10+.
+
+| Memory | Flag | Download | Notes |
+|---|---|---|---|
+| 32 GB+ | default (`bf16`) | ~15 GB | Reference quality |
+| 16 GB | `--precision 4bit` | ~4.5 GB | Runs, but output degrades visibly (repetition, tone errors) |
+
+```bash
+pip install tujia-llm                          # after the PyPI release
+pip install dist/tujia_llm-0.2.0-py3-none-any.whl   # offline / local wheel
+```
+
+The wheel contains code only. Weights (74 MB) and the base model are downloaded on first run.
+
+## CLI
+
+```bash
+tujia-llm info                                  # backend, precision, memory
+tujia-llm lookup 酒
+tujia-llm translate "大家都过好日子。"
+tujia-llm translate "大家都过好日子，土家人们都相好。" --split
+tujia-llm translate "zɤ³⁵" --to zh
+tujia-llm translate "zɤ³⁵" --to en
+```
+
+Options: `--adapter` (local directory or HF repo id), `--precision auto|bf16|4bit`,
+`--max-tokens`, `--json`.
+
+```bash
+tujia-llm lookup 酒 --adapter /path/to/adapter-dir --json
+```
+
+For development, `python scripts/infer.py` offers the same prompts without installation.
+
+## Windows / CPU (GGUF)
+
+The MLX build is Apple Silicon only. For Windows, Linux, and Intel Macs use the GGUF build
+with llama.cpp or Ollama — see [docs/windows-gguf.md](docs/windows-gguf.md).
+
+| File | Size | Memory |
+|---|---|---|
+| `gguf/tujia-llm-8b-v0.2-Q4_K_M.gguf` | 4.7 GB | 16 GB+ |
+| `gguf/tujia-llm-8b-v0.2-f16.gguf` | 15 GB | 20 GB+ |
+
+```powershell
+ollama create tujia -f gguf/Modelfile
+ollama run tujia "「酒」用土家语怎么说？"
+```
+
+## Capabilities and limits
+
+**Works**
+
+- Chinese word → Tujia form + IPA (reliable for high-frequency words)
+- Chinese short sentence → Tujia sentence (stable up to roughly 8 syllables)
+- Tujia sentence → English
+
+**Does not work**
+
+- Authoritative translation, publication-grade text, legal or medical use
+- Folk songs, ritual language, and other low-resource registers
+- Southern Tujia (Luxi) and non-Longshan varieties such as Baojing
+- Out-of-vocabulary words: there is no refusal mechanism, so the model will invent forms
+
+## Evaluation summary
+
+| Metric | Base | v0.2 |
+|---|---|---|
+| Lexicon 500, first-candidate exact | 0% | 5.8% |
+| Lexicon 500, edit similarity | 0.020* | 0.511 |
+| Single-entry 250, similarity | 0.024* | 0.449 |
+| Sentences 100, similarity (split decoding) | 0.082 | 0.451 |
+| Song lyrics, 12 lines, similarity | — | 0.583 |
+
+\* Base model evaluated on the first 100 items only, so not directly comparable to the full sets.
+
+Full tables, dialect breakdowns, and failure modes: [docs/eval-v0.2.md](docs/eval-v0.2.md).
+
+## Prompt format
+
+The model was trained on four fixed templates. Keep them unchanged at inference time:
+
+```
+「{Chinese word}」用土家语怎么说？
+把这句话翻译成土家语：{Chinese sentence}
+把这句话翻译成汉语：{Tujia sentence}
+把这句话翻译成英语：{Tujia sentence}
+```
+
+Output uses mixed Ye pinyin / IPA notation with superscript tone digits, e.g. `zɤ³⁵`.
+
+## Layout
+
+```
+scripts/infer.py        inference example
+docs/eval-v0.2.md       evaluation report
+release/                release config and upload script
+MODEL_CARD.md           model card
+NOTICE                  usage boundaries
+```
+
+## Citation
+
+```bibtex
+@misc{tujia-llm-v0.1,
+  title  = {tujia-llm: LoRA adapter for Tujia language generation (v0.2)},
+  author = {ibaibing},
+  year   = {2026},
+  note   = {Research preview}
+}
+```

tujia_llm-0.2.0/tujia_llm.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+NOTICE
+README.md
+pyproject.toml
+tujia_llm/__init__.py
+tujia_llm/__main__.py
+tujia_llm/backend_mlx.py
+tujia_llm/cli.py
+tujia_llm/config.py
+tujia_llm.egg-info/PKG-INFO
+tujia_llm.egg-info/SOURCES.txt
+tujia_llm.egg-info/dependency_links.txt
+tujia_llm.egg-info/entry_points.txt
+tujia_llm.egg-info/requires.txt
+tujia_llm.egg-info/top_level.txt

tujia_llm-0.2.0/tujia_llm.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tujia_llm-0.2.0/tujia_llm.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tujia-llm = tujia_llm.cli:main

tujia_llm-0.2.0/tujia_llm.egg-info/requires.txt

@@ -0,0 +1,4 @@
+huggingface_hub>=0.24
+
+[:sys_platform == "darwin" and platform_machine == "arm64"]
+mlx-lm>=0.21

tujia_llm-0.2.0/tujia_llm.egg-info/top_level.txt

@@ -0,0 +1 @@
+tujia_llm