Upload 3 files

DOCS.md

@@ -1,110 +1,204 @@
 # voice — Help
 
-> Generated from `voice --help` and `voice <cmd> --help` (`voice.py` 7 cmds). Build mode.
+Generated from `voice --help` and `voice <cmd> --help` (v2.0.0, 11 commands).
 
 ## voice --help
 
 ```
-usage: voice [-h] [-v] {get,cast,path,remove,list,delta,info} ...
+usage: voice [-h] [-v] [--non-interactive] [--version]
+             [--completion {bash,zsh,fish}]
+             {get,cast,tensor,delta,list,info,remove,cleanup,auth,path,doctor} ...
 
-Get a voice, then cast it onto your model.
+Lift a model's voice and cast it onto another model.
 
 positional arguments:
-  {get,cast,path,remove,list,delta,info}
-    get                 Get a voice from a HuggingFace model
-    cast                Cast a voice onto your model
-    path                Add 'voice' to your system PATH
-    remove              Remove a stored voice
+  {get,cast,tensor,delta,list,info,remove,cleanup,auth,path,doctor}
+    get                 Get a voice from a model (safetensors repo, .gguf, or URL)
+    cast                Cast a voice onto a .gguf or .safetensors file
+    tensor              Extract or cast any named tensor
+    delta               Make a reusable style (voice − base)
     list                List stored voices
-    delta               Make a style you can re-use (voice − base)
-    info                Show voice metadata
+    info                Show voice details
+    remove              Remove a stored voice
+    cleanup             Remove incomplete downloads
+    auth                Save your HF token (optional)
+    path                Put voice on your PATH
+    doctor              Check your setup
 
 options:
   -h, --help            show this help message and exit
-  -v, --verbose         Show detailed progress
+  -v, --verbose
+  --non-interactive
+  --version
+  --completion {bash,zsh,fish}
 ```
 
-## voice get --help
+## voice get
 
 ```
-usage: voice get [-h] [-q] model_id
+usage: voice get [-h] [-q] [--name NAME] [--yes] source
+
+Get a voice from a model (safetensors repo, .gguf, or URL)
 
 positional arguments:
-  model_id     HuggingFace model ID (e.g. google/gemma-3-1b)
+  source      HF model ID, .gguf/.safetensors path, or URL
 
 options:
-  -h, --help   show this help message and exit
-  -q, --quiet  Skip license detection
+  -h, --help  show this help message and exit
+  -q, --quiet Skip license detection
+  --name NAME Voice name to save
+  --yes       Auto-confirm overwrites
 ```
 
-## voice delta --help
+## voice cast
 
 ```
-usage: voice delta [-h] [voicename]
+usage: voice cast [-h] [--out OUT] [--yes] target voice
+
+Cast a voice onto a .gguf or .safetensors file
 
 positional arguments:
-  voicename   Voice name from registry (from voice list)
+  target      Path to the target .gguf or .safetensors
+  voice       Voice name, or a .safetensors/.gguf path
 
 options:
   -h, --help  show this help message and exit
+  --out OUT   Output file (default: alongside the target)
+  --yes       Auto-confirm overwrites
+```
+
+## voice tensor
+
+```
+usage: voice tensor [-h] {get,cast} ...
+
+Extract or cast any named tensor
 ```
 
-## voice cast --help
+### voice tensor get
 
 ```
-usage: voice cast [-h] [--out OUT] target_gguf voice
+usage: voice tensor get [-h] [--tensor TENSOR] [--out OUT] [--yes] source
+
+Extract any named tensor to a .safetensors file
 
 positional arguments:
-  target_gguf  Path to the target GGUF model
-  voice        Voice name (from registry) or path to .safetensors
+  source          HF model ID, .gguf/.safetensors path, or URL
 
 options:
-  -h, --help   show this help message and exit
-  --out OUT    Output directory or file (default:
-               ./<model>/<voice>-<model>.gguf)
+  --tensor TENSOR Tensor name (default: auto-detect the output head)
+  --out OUT       Output .safetensors path
+  --yes           Auto-confirm overwrites
 ```
 
-## voice list --help
+### voice tensor cast
 
 ```
-usage: voice list [-h] [{base}]
+usage: voice tensor cast [-h] [--tensor TENSOR] [--out OUT] [--yes] target tensor_file
+
+Cast any named tensor onto a .gguf or .safetensors file
 
 positional arguments:
-  {base}      List bases instead of voices (voice list base)
+  target          Path to the target .gguf or .safetensors
+  tensor_file     Path to a .safetensors/.gguf containing the tensor
 
 options:
-  -h, --help  show this help message and exit
+  --tensor TENSOR Tensor name (default: the file's output head or only tensor)
+  --out OUT       Output file
+  --yes           Auto-confirm overwrites
 ```
 
-## voice info --help
+## voice delta
 
 ```
-usage: voice info [-h] voicename
+usage: voice delta [-h] [--base BASE] [--yes] [voicename]
+
+Make a reusable style (voice − base)
 
 positional arguments:
-  voicename   Voice name to show info for
+  voicename    Voice name from registry (from voice list)
 
 options:
-  -h, --help  show this help message and exit
+  -h, --help   show this help message and exit
+  --base BASE  Base HF repo (org/model)
+  --yes        Auto-confirm overwrites
 ```
 
-## voice remove --help
+## voice list
 
 ```
-usage: voice remove [-h] voice
+usage: voice list [-h] [--base] [{base}]
+
+List stored voices
 
 positional arguments:
-  voice       Voice name to remove
+  {base}       List bases instead of voices
+
+options:
+  -h, --help   show this help message and exit
+  --base       List cached base heads (alias for 'voice list base')
+```
+
+## voice info
+
+```
+usage: voice info [-h] voicename
+
+Show voice details
+```
+
+## voice remove
+
+```
+usage: voice remove [-h] [--yes] voice
+
+Remove a stored voice
+```
+
+## voice cleanup
+
+```
+usage: voice cleanup [-h] [--force]
+
+Remove incomplete downloads
 
 options:
   -h, --help  show this help message and exit
+  --force     Remove even active downloads
 ```
 
-## voice path --help
+## voice auth
 
 ```
-usage: voice path [-h]
+usage: voice auth [-h] [--clear] [--show]
+
+Save your HF token (optional)
 
 options:
   -h, --help  show this help message and exit
+  --clear     Remove stored token
+  --show      Show if token is present (masked)
+```
+
+## voice path
+
+```
+usage: voice path [-h]
+
+Put voice on your PATH
+```
+
+## voice doctor
+
+```
+usage: voice doctor [-h]
+
+Check your setup
+```
+
+## voice --version
+
+```
+voice --version           # show version + environment
+voice --completion bash|zsh|fish   # print shell completion
 ```

README.md

@@ -76,12 +76,30 @@ No adapter at runtime. `voice cast` bakes the voice into a complete `.gguf` —
 
 ---
 
+## The Idea — a scalpel for the community
+
+Voice is a **scalpel, not a pipeline** — built for fast experimentation and iteration. One idea made trivial: lift a model's character and place it elsewhere, without friction, without hiccups.
+
+**Backed by proven ideas:**
+
+* **QAT-aware bases** — Google's Quantization-Aware Training (5k steps, fake-quant + KL to BF16) shows 54% less perplexity drop at Q4_0. The best base stays intact.
+* **`lm_head` carries style** — the MythoMax lineage and Gryphe's StyleTune proved one tensor changes voice. We just make it portable.
+
+**What that trivializes:**
+
+* **Any format → any format:** `voice get` lifts the output-projection from **any** source — a Hugging Face `safetensors` repo, a local `.gguf`, or a direct URL — with range requests (no full download). `voice cast` fuses it onto **any** target — a `.gguf` *or* a `.safetensors` file. Transposes `[vocab, hidden]` ↔ `[hidden, vocab]` and `BF16`/`F16`/`F32` → `F32` → `Q8_0` automatically. The rest of the model is byte-copied.
+* **Any tensor, anywhere:** `voice tensor get <source> --tensor <name>` extracts **any named tensor** from any file, `voice tensor cast <target> <file> [--tensor <name>]` drops it into any other file — GGUF-quant passthrough stays bit-exact when source and target share quantization, dequant-then-requant when crossing to safetensors, all with the same one-liner.
+* **No surprises:** atomic writes, validated `safetensors` offsets, ETag-aware resume, verified HF token handling (0600), symlink-safe registry — so repeated `get`/`cast` on flaky links or shared disks just resumes or fails cleanly.
+
+Result: keep the stronger model for reasoning, the better voice for style, and iterate in seconds. Mix Holodeck → Qwen, Darkside → Gemma, Serenity + Darkside, QAT + StyleTune — one file out, `llama serve -m` ready.
+
+
 ## How it works
 
 Two benefits, no extras to learn:
 
-- **Get what you need:** Light and fast — pulled with range requests in seconds, saved as one tensor (`voice.safetensors` + `voice.json`). `voice list` to see, `voice info` to inspect.
-- **Run fused:** Cast writes a complete model you can run anywhere. No extra setup.
+- **Get what you need:** Light and fast — pulled with range requests in seconds, saved as one tensor (`voice.safetensors` or `voice.gguf` for quant passthrough + `voice.json`). `voice list` to see, `voice info` to inspect.
+- **Run fused:** Cast writes a complete model you can run anywhere. No extra setup. Quant voices stay bit-exact `Q8_0`→`Q8_0`.
 
 You will see each step as it happens and get a ready-to-run file at the end.
 
@@ -102,17 +120,22 @@ A delta carries only the difference from its base, so it blends more gently with
 
 ## Commands
 
-Seven verbs. One idea each:
-
-| Command | Description |
-|---|---|
-| `voice get <org/model>` | Get a voice from Hugging Face and save it to your library |
-| `voice delta [name]` | Make a portable style you can reuse across compatible models |
-| `voice cast <model.gguf> <voice>` | Fuse a voice into your model and write a complete, ready-to-run file |
-| `voice list` | Show your saved voices—add `base` to list cached bases |
-| `voice info <voice>` | Show details for a saved voice or delta |
-| `voice remove <voice>` | Remove a voice from your library |
-| `voice path` | Add `voice` to your PATH |
+Commands. One idea each — 11 commands, `voice --help` is the source of truth (`DOCS.md` generated from live `voice.py` v2.0.0):
+
+| Command | Description | Source |
+|---|---|---|
+| `voice get <model>` | Get a voice from a safetensors repo, `.gguf`, or URL (any format in) | `voice.py:1512` `cmd_get` |
+| `voice cast <target> <voice>` | Fuse a voice onto a `.gguf` or `.safetensors` file (any format out) | `voice.py:1616` `cmd_cast` |
+| `voice tensor get <source> --tensor <n>` | Extract **any** named tensor to a standalone artifact (safetensors or gguf for quant) | `voice.py:1890` `cmd_tensor_get` |
+| `voice tensor cast <target> <file>` | Cast **any** named tensor onto a `.gguf` or `.safetensors` file | `voice.py:1942` `cmd_tensor_cast` |
+| `voice delta [name]` | Make a portable style (`voice − base` → `F16` delta) you can reuse across compatible models | `voice.py:1999` `cmd_delta` |
+| `voice list [base]` | Show saved voices — `voice list base` shows cached base heads | `voice.py:2289` `cmd_list` |
+| `voice info <voice>` | Show details for a saved voice, delta, or cached base | `voice.py:2303` `cmd_info` |
+| `voice remove <voice>` | Remove a voice from your library | `voice.py:2347` `cmd_remove` |
+| `voice cleanup [--force]` | Remove incomplete downloads (`.parts`) — skips active (<10 min) unless `--force` | `voice.py:2365` `cmd_cleanup` |
+| `voice auth [--show\|--clear]` | Save your HF token (0600, optional, faster/verified) | `voice.py:2388` `cmd_auth` |
+| `voice path` | Put `voice` on your PATH (symlink to `/usr/local/bin` or `~/.local/bin`) | `voice.py:2435` `cmd_path` |
+| `voice doctor` | Check your setup — Python + uv + venv + disk + HF token + connectivity | `voice.py:2471` `cmd_doctor` |
 
 Example:
 
@@ -130,7 +153,7 @@ voice list base
 voice cast ./model.gguf styletune-v2 --out ./voiced/
 ```
 
-> `delta-` is reserved. Voice names cannot start with it. Deltas always do. Full CLI reference: [`DOCS.md`](./DOCS.md) (generated from `voice --help`, 7 commands). Names are lowercased when saved.
+> `delta-` is reserved. Voice names cannot start with it. Deltas always do. Full CLI reference: [`DOCS.md`](./DOCS.md) (generated from `voice --help`, 11 commands). Names are lowercased when saved.
 
 
 ## What StyleTune showed
@@ -228,7 +251,7 @@ curl http://localhost:8080/v1/chat/completions \
 
 ### Transformers (HF-native snippet—for the base or other safetensors voices)
 
-The Voice tool extracts the `lm_head` from `safetensors` models. For any HF `transformers` model (including the base below), the canonical snippet is:
+The Voice tool extracts the output-projection tensor (`lm_head` and friends) from safetensors or GGUF models. For any HF `transformers` model (including the base below), the canonical snippet is:
 
 ```python
 from transformers import pipeline