amv-train 0.0.0-stage → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/LICENSE +57 -0
  2. package/NOTICE +17 -0
  3. package/README.md +388 -2
  4. package/README.pypi.md +90 -0
  5. package/bin/cli.js +224 -0
  6. package/index.d.ts +182 -0
  7. package/index.js +39 -0
  8. package/lib/benchmark.js +118 -0
  9. package/lib/doctor.js +149 -0
  10. package/lib/errors.js +60 -0
  11. package/lib/multimodal.js +95 -0
  12. package/lib/trainer.js +350 -0
  13. package/package.json +55 -4
package/LICENSE ADDED
@@ -0,0 +1,57 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work.
38
+
39
+ 2. Grant of Copyright License. Subject to the terms and conditions of
40
+ this License, each Contributor hereby grants to You a perpetual,
41
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
42
+ copyright license to reproduce, prepare Derivative Works of,
43
+ publicly display, publicly perform, sublicense, and distribute the
44
+ Work and such Derivative Works in Source or Object form.
45
+
46
+ 3. Grant of Patent License. Subject to the terms and conditions of
47
+ this License, each Contributor hereby grants to You a perpetual,
48
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
49
+ patent license to make, have made, use, offer to sell, sell, import,
50
+ and otherwise transfer the Work.
51
+
52
+ 4. Redistribution. You may reproduce and distribute copies of the
53
+ Work or Derivative Works thereof in any medium, with or without
54
+ modifications, and in Source or Object form, provided that You
55
+ meet the conditions of this License.
56
+
57
+ END OF TERMS AND CONDITIONS
package/NOTICE ADDED
@@ -0,0 +1,17 @@
1
+ amv-train
2
+ Copyright 2026 amv-train contributors
3
+
4
+ This product includes software developed by the amv-train project
5
+ (https://github.com/uno-km/amv-train) and AMEVA Open-Source Foundation.
6
+
7
+ Licensed under the Apache License, Version 2.0 (the "License");
8
+ you may not use this file except in compliance with the License.
9
+ You may obtain a copy of the License at
10
+
11
+ http://www.apache.org/licenses/LICENSE-2.0
12
+
13
+ Unless required by applicable law or agreed to in writing, software
14
+ distributed under the License is distributed on an "AS IS" BASIS,
15
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
+ See the License for the specific language governing permissions and
17
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,389 @@
1
- # Temporary Holding Version
1
+ # AMV-Train (v2.0.0)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **마이그레이션 안내**: 이 패키지는 `termux-train`에서 `amv-train`로 이름이 바뀌었습니다. 기존 `termux-train` 배포본(PyPI/npm)은 호환을 위해 당분간 유지되나 deprecated 상태이며 더 이상 갱신되지 않습니다. `pip install amv-train` / `npm install amv-train`로 전환하십시오.
4
+ >
5
+ > Android **Termux 환경** 또는 **안드로이드 Linux 커널(루팅 없이 Linux 환경이 구동되는 모든 디바이스)** 에서 동작합니다 — Termux 전용이 아닙니다.
6
+
7
+ [![PyPI](https://img.shields.io/pypi/v/amv-train.svg?style=flat-square&color=0369a1)](https://pypi.org/project/amv-train/)
8
+ [![Python](https://img.shields.io/pypi/pyversions/amv-train.svg?style=flat-square)](https://pypi.org/project/amv-train/)
9
+ [![npm](https://img.shields.io/npm/v/amv-train.svg?style=flat-square&color=b91c1c)](https://www.npmjs.com/package/amv-train)
10
+ [![npm downloads](https://img.shields.io/npm/dm/amv-train.svg?style=flat-square&color=b91c1c)](https://www.npmjs.com/package/amv-train)
11
+ [![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/amv-train)
12
+
13
+ > **Unified Multimodal On-Device Deep Learning & LoRA Training Framework for Android Termux with 6-Modality Adapters (LLM, Diffusion, VLM, STT, TTS, BitNet), GPU Slicing, and 44GB Disaggregated Cluster Virtual RAM Pooling**
14
+
15
+ ---
16
+
17
+ ## What's New in v2.1.0 — Vulkan Backend Line-Break Syntax Patch & DAG Autograd Hardening
18
+
19
+ - Fixed CRLF line-break syntax error in Vulkan compute shader backend.
20
+ - Hardened SafeTensors zero-copy memory mapping and LoRA gradient accumulation.
21
+ - Standardized Apache-2.0 SPDX license headers and published npm package v2.1.0.
22
+
23
+ ---
24
+
25
+ ## Executive Summary & Architecture Overview
26
+
27
+ **AMV-Train v2.0.0** is an industrial-grade, zero-dependency deep learning framework engineered specifically for constrained ARM64 Bionic environments (Android Termux, mobile Linux, embedded edge devices). By combining a C-vectorized Directed Acyclic Graph (DAG) Autograd runtime with mobile hardware acceleration (Vulkan Compute, OpenCL, ARM64 NEON), AMV-Train enables full backward gradient propagation, parameter-efficient fine-tuning (LoRA / DoRA), and reinforcement learning directly on mobile devices.
28
+
29
+ ```
30
+ +---------------------------------------------------------------------------------------------------+
31
+ | TERMUX-TRAIN v2.0.0 |
32
+ | Unified Multimodal On-Device Deep Learning Engine |
33
+ +---------------------------------------------------------------------------------------------------+
34
+ |
35
+ +-----------------------------------------+-----------------------------------------+
36
+ | |
37
+ v v
38
+ +-------------------------------+ +-------------------------------+
39
+ | 6-Modality Adapters | | Memory & Scaling Subsys |
40
+ | - LLM / DoRA / TinyLM | | - Single-Device GPU Slicing |
41
+ | - Image Diffusion LoRA | | * Vocab Slicing |
42
+ | - Vision Multimodal (VLM) | | * Chunked Layer Dispatch |
43
+ | - Whisper STT Acoustic LoRA | | * Layer Streaming |
44
+ | - Speech TTS Style LoRA | | - 44GB Cluster Virtual RAM |
45
+ | - BitNet 1.58-bit Ternary | | - 300MB Guard-Band Memory |
46
+ +-------------------------------+ +-------------------------------+
47
+ | |
48
+ +-----------------------------------------+-----------------------------------------+
49
+ |
50
+ v
51
+ +---------------------------------------------------------------------------------------------------+
52
+ | Target-Aware Runtime Export & Compatibility |
53
+ | ComfyUI / Diffusers | llama.cpp / GGUF | amv-vision | amv-stt | BitNet |
54
+ +---------------------------------------------------------------------------------------------------+
55
+ ```
56
+
57
+ ### Core Architectural Pillars
58
+
59
+ 1. **Zero External Heavy Dependencies**: Executes autonomously without PyTorch, LibTorch, CMake, or heavy BLAS runtimes. Pure Python DAG autograd paired with optional C-accelerator ABI (`libamv_train_accel.so`) or Vulkan compute shaders.
60
+ 2. **6-Modality Target-Aware Adapters**: Generates standard SafeTensors weights and companion `_config.json` manifests natively recognized by major desktop and mobile inference runtimes without conversion tooling.
61
+ 3. **Single-Device GPU Slicing**: Bypasses mobile Unified Memory Architecture (UMA) spikes and watchdog timeouts on ARM Mali and Qualcomm Adreno GPUs through granular vocabulary chunking and layer streaming.
62
+ 4. **44GB Disaggregated Cluster Virtual RAM Pooling**: Binds physical memory across heterogeneous mobile nodes (e.g., Galaxy S25, S21, S20, A53, A35) into an aggregated pipeline training session protected by a 300MB memory Guard-Band against the Android Low Memory Killer (LMK).
63
+ 5. **100% Dual-Engine Parity**: Complete feature and interface symmetry across Python CLI (`amv-train`), Node.js Global CLI (`amv-train`), Python Library (`import amv_train`), and Node.js SDK (`import { ... } from 'amv-train'`).
64
+
65
+ ---
66
+
67
+ ## Installation
68
+
69
+ ### 1. Via Python Package Index (PyPI)
70
+ ```bash
71
+ pip install amv-train
72
+ ```
73
+
74
+ ### 2. Via Node Package Manager (npm)
75
+ ```bash
76
+ npm install -g amv-train
77
+ ```
78
+
79
+ ### 3. Standalone Bootstrap Script (Termux One-Liner)
80
+ ```bash
81
+ pkg update && pkg install -y python nodejs clang
82
+ bash <(curl -sSL https://raw.githubusercontent.com/uno-km/amv-train/main/install.sh)
83
+ ```
84
+
85
+ ---
86
+
87
+ ## 6-Modality Training Pipelines & CLI Reference
88
+
89
+ ### 1. Image Diffusion LoRA Training (`diffusion-train`)
90
+ Trains latent diffusion cross-attention LoRA layers. Integrates a deterministic DDPM noise scheduler, sinusoidal timestep MLP, and SHA-256 disk-based VAE latent caching to eliminate redundant image decoding across epochs. Outputs ComfyUI- and Diffusers-compatible SafeTensors adapters.
91
+
92
+ ```bash
93
+ amv-train diffusion-train \
94
+ --image-dir ./training_images \
95
+ --prompt "high quality product photograph, 4k" \
96
+ --output ./adapter_diffusion.safetensors \
97
+ --resolution 512 \
98
+ --epochs 5 \
99
+ --batch-size 1 \
100
+ --lr 0.0001 \
101
+ --rank 8 \
102
+ --alpha 16.0 \
103
+ --backend vulkan
104
+ ```
105
+
106
+ ### 2. Vision Multimodal VLM LoRA Training (`vision-train`)
107
+ Trains multimodal projection adapters and visual cross-attention layers. Operates on image-text pairs formatted in LLaVA or Qwen2-VL visual question answering schemas. Directly bridges into the `amv-vision` mobile inference runtime.
108
+
109
+ ```bash
110
+ amv-train vision-train \
111
+ --data ./vlm_dataset.jsonl \
112
+ --output ./adapter_vision.safetensors \
113
+ --epochs 3 \
114
+ --batch-size 2 \
115
+ --lr 0.0002 \
116
+ --rank 8 \
117
+ --alpha 16.0 \
118
+ --backend vulkan
119
+ ```
120
+
121
+ ### 3. Speech-to-Text Whisper LoRA Training (`stt-train`)
122
+ Performs acoustic adaptation on Whisper encoder-decoder attention blocks. Features automated Mel filterbank spectrogram extraction and persistent caching. Natively consumable by `amv-stt`.
123
+
124
+ ```bash
125
+ amv-train stt-train \
126
+ --data ./speech_corpus.jsonl \
127
+ --output ./adapter_stt.safetensors \
128
+ --epochs 4 \
129
+ --batch-size 4 \
130
+ --lr 0.0005 \
131
+ --rank 4 \
132
+ --backend vulkan
133
+ ```
134
+
135
+ ### 4. Text-to-Speech Style Adaptation LoRA Training (`tts-train`)
136
+ Fine-tunes speaker embedding and acoustic style parameters for neural speech synthesis. Generates low-rank voice profile adapters directly compatible with `amv-tts`.
137
+
138
+ ```bash
139
+ amv-train tts-train \
140
+ --data ./voice_samples.jsonl \
141
+ --output ./adapter_tts.safetensors \
142
+ --epochs 5 \
143
+ --batch-size 2 \
144
+ --lr 0.0003 \
145
+ --rank 4 \
146
+ --backend cpu
147
+ ```
148
+
149
+ ### 5. Large Language Model PEFT (`train` / `peft`)
150
+ Trains LoRA / DoRA weight matrices over multi-head attention and feed-forward projections with RoPE positional encodings. Supports single-device GPU slicing flags to eliminate out-of-memory crashes on mobile GPUs. Exports standard GGUF PEFT adapters for `llama.cpp`.
151
+
152
+ ```bash
153
+ amv-train train \
154
+ --model tiny-transformer \
155
+ --data ./training_corpus.txt \
156
+ --output ./adapter_llm.safetensors \
157
+ --epochs 3 \
158
+ --lr 0.0002 \
159
+ --lora-rank 8 \
160
+ --lora-alpha 16.0 \
161
+ --vocab-slice 4096 \
162
+ --chunk-layers 2 \
163
+ --stream-layers \
164
+ --backend vulkan
165
+ ```
166
+
167
+ ### 6. BitNet 1.58-bit Ternary Quantization-Aware Training
168
+ Applies dynamic activation scaling and ternary weight quantization $\{-1, 0, +1\}$ during forward and backward passes. Directly exports quantized kernels compatible with `bitnet.cpp` and `amv-bitnet`.
169
+
170
+ ```bash
171
+ amv-train train \
172
+ --model bitnet \
173
+ --quantize-bits 1.58 \
174
+ --data ./corpus.txt \
175
+ --output ./bitnet_adapter.safetensors \
176
+ --backend opencl
177
+ ```
178
+
179
+ ---
180
+
181
+ ## Complete Parameter Reference Matrix
182
+
183
+ | Parameter Flag | Type | Default | Applicable Subcommands | Engineering Semantics & Usage Description |
184
+ | :--- | :--- | :--- | :--- | :--- |
185
+ | `--image-dir` | String | *Required* | `diffusion-train` | Absolute or relative path to directory containing source training images (`.png`, `.jpg`). |
186
+ | `--prompt` | String | `""` | `diffusion-train` | Conditioning text prompt applied across image diffusion training instances. |
187
+ | `--resolution` | Integer | `512` | `diffusion-train` | Input image dimension for latent VAE spatial encoding ($H=W$). |
188
+ | `--data` | String | *Required* | `vision-train`, `stt-train`, `tts-train`, `train`, `rl` | Path to dataset file (`.jsonl`, `.txt`, `.csv`). |
189
+ | `--output` | String | *Required* | All training subcommands | Destination filepath for exported `.safetensors` adapter file. |
190
+ | `--epochs` | Integer | `3` | All training subcommands | Total complete passes over the dataset. |
191
+ | `--batch-size` | Integer | `1` | All training subcommands | Micro-batch size per training step. |
192
+ | `--lr` | Float | `0.0001` | All training subcommands | Optimization learning rate for AdamW / SGD gradient update. |
193
+ | `--rank` / `--lora-rank` | Integer | `8` | All training subcommands | Inner rank dimension $r$ for LoRA projection matrices $A \in \mathbb{R}^{r \times d_{in}}$ and $B \in \mathbb{R}^{d_{out} \times r}$. |
194
+ | `--alpha` / `--lora-alpha`| Float | `16.0` | All training subcommands | Scaling hyperparameter $\alpha$ for LoRA weight contribution ($\Delta W = \frac{\alpha}{r} BA$). |
195
+ | `--backend` | String | `auto` | All subcommands | Compute acceleration backend: `auto`, `vulkan`, `opencl`, `cpu`. |
196
+ | `--vocab-slice` | Integer | `0` (off) | `train`, `peft` | Granular vocabulary partition size to prevent GPU out-of-memory spikes during softmax cross-entropy. |
197
+ | `--chunk-layers` | Integer | `0` (off) | `train`, `peft` | Number of sequential transformer layers evaluated per GPU dispatch to prevent OS watchdog timeout resets. |
198
+ | `--stream-layers` | Boolean | `false` | `train`, `peft` | Dynamically streams inactive layer weights between system RAM and GPU buffer memory. |
199
+ | `--virtual-ram-pool` | String | `""` | `train`, `diffusion-train`, `peft` | Cluster connection endpoint (`host:port`) binding local training session to aggregated virtual RAM pool. |
200
+ | `--guard-band` | Integer | `300` | `cluster-worker`, `train` | Reserved unallocated system RAM buffer (in MB) preventing Android Low Memory Killer (LMK) aborts. |
201
+ | `--method` | String | `grpo` | `rl` | Reinforcement learning optimization algorithm: `grpo`, `dpo`, `ppo`. |
202
+ | `--group-size` | Integer | `4` | `rl` | Generation group candidate size for Group Relative Policy Optimization (GRPO). |
203
+ | `--beta` | Float | `0.1` | `rl` | KL divergence regularization coefficient for DPO and GRPO reference policy stabilization. |
204
+ | `--host` | String | `0.0.0.0` | `cluster-worker`, `cluster-probe`| Network host address for disaggregated virtual RAM clustering daemon. |
205
+ | `--port` | Integer | `50052` | `cluster-worker`, `cluster-probe`| Network TCP port for cluster worker coordination. |
206
+
207
+ ---
208
+
209
+ ## Single-Device GPU Slicing Architecture
210
+
211
+ On mobile platforms, the GPU and CPU share a Unified Memory Architecture (UMA). Large batch matrix multiplications during autograd activation accumulation trigger sudden memory surges that prompt the Android system to issue SIGKILL signals. Furthermore, ARM Mali GPU driver stacks enforce a hardware watchdog timeout: any single compute command buffer executing longer than 2.0 seconds is terminated with `VK_ERROR_DEVICE_LOST`.
212
+
213
+ ```
214
+ MOBILE UNIFIED RAM (LPDDR5)
215
+ +-------------------------------------------------------------------------+
216
+ | OS Kernel / Termux Base | Active Layer Buffer | Guard-Band Buffer (300MB)|
217
+ +-------------------------------------------------------------------------+
218
+ ^
219
+ | Layer Streaming Swap
220
+ v
221
+ VULKAN / OPENCL GPU ENGINE
222
+ +-------------------------------------------------------------------------+
223
+ | [Vocab Chunk 1] -> [Vocab Chunk 2] | [Layer N] -> [Layer N+1] (Chunked) |
224
+ +-------------------------------------------------------------------------+
225
+ ```
226
+
227
+ To neutralize these constraints:
228
+ - **Vocab Slicing (`--vocab-slice 4096`)**: Partitions vocabulary projection matrices into slices of 4,096 tokens, performing sequential cross-entropy reductions with minimal temporary tensor overhead.
229
+ - **Chunked Layer Dispatch (`--chunk-layers 2`)**: Segments multi-layer transformer forward-backward passes into 2-layer dispatches, returning control to the Vulkan queue to reset watchdog timers.
230
+ - **Layer Streaming (`--stream-layers`)**: Maintains only active weight layers inside device GPU memory buffers, paging inactive weights into host RAM.
231
+
232
+ ---
233
+
234
+ ## 44GB Disaggregated Cluster Virtual RAM Pooling (Powered by AMEVA Cluster)
235
+
236
+ > [!IMPORTANT]
237
+ > **Prerequisite: Official AMEVA Cluster Runtime (`ameva-cluster`) Required**
238
+ > Multi-device distributed memory pooling and cross-device tensor pipeline execution require the official **`ameva-cluster`** control plane. Single-device training (CPU, Vulkan, OpenCL) runs entirely standalone, but distributed cluster pooling features will raise `ClusterLicenseRequiredError` (E403) unless `ameva-cluster` is installed.
239
+ > ```bash
240
+ > pip install ameva-cluster amv-train
241
+ > # or via npm:
242
+ > npm install -g @ameva/cluster amv-train
243
+ > ```
244
+
245
+ When training deep learning models that exceed physical mobile device memory (e.g. 7B+ parameter models, high-resolution diffusion unets, or multimodal projectors), AMV-Train binds heterogeneous smartphone clusters into a unified virtual memory pool. Idle mobile devices contribute unallocated LPDDR RAM via lightweight worker daemons managed by AMEVA Cluster.
246
+
247
+ ```
248
+ +-------------------------------------------------------------------------+
249
+ | COORDINATOR / PRIMARY NODE (Galaxy S25 - 12GB) |
250
+ | Directs Training Pipeline & Weight Updates |
251
+ +-------------------------------------------------------------------------+
252
+ | | |
253
+ gRPC/HTTP RPC gRPC/HTTP RPC gRPC/HTTP RPC
254
+ (MasterTunnel) (MasterTunnel) (MasterTunnel)
255
+ v v v
256
+ +--------------------+ +--------------------+ +--------------------+
257
+ | WORKER 1 (S21) | | WORKER 2 (S20) | | WORKER 3 (A53/A35) |
258
+ | RAM: 8GB LPDDR5 | | RAM: 12GB LPDDR5 | | RAM: 12GB LPDDR4X |
259
+ | Dedicated: 6.8GB | | Dedicated: 10.5GB | | Dedicated: 9.2GB |
260
+ +--------------------+ +--------------------+ +--------------------+
261
+ \ | /
262
+ +--------------------------+--------------------------+
263
+ |
264
+ v
265
+ TOTAL AGGREGATED VIRTUAL POOL: ~44GB
266
+ ```
267
+
268
+ ### Complete Cluster Step-by-Step Operation Manual
269
+
270
+ #### Step 1: Network & Environment Setup
271
+ Ensure all participating smartphones are connected to the same local Wi-Fi network, router, or tethered hotspot. Verify TCP port `50052` is accessible between nodes:
272
+ ```bash
273
+ pkg update && pkg install -y python clang netcat-openbsd
274
+ pip install --upgrade ameva-cluster amv-train
275
+ ```
276
+
277
+ #### Step 2: Launching Cluster Workers on Contributor Nodes
278
+ On each memory-contributor smartphone (e.g., Galaxy S21, S20, A53), start the worker daemon. The `--guard-band 300` flag reserves 300MB of unallocated system RAM at all times to prevent the Android Low Memory Killer (LMK) from terminating processes:
279
+ ```bash
280
+ # Option A: Directly through ameva-cluster
281
+ ameva-cluster worker --port 50052 --guard-band 300
282
+
283
+ # Option B: Through amv-train CLI bridge
284
+ amv-train cluster-worker --port 50052 --guard-band 300
285
+ ```
286
+
287
+ #### Step 3: Probing and Discovering Fleet Nodes
288
+ On your primary coordinator smartphone (e.g., Galaxy S25), run a cluster probe to inspect node reachability, available LPDDR memory headroom, and network round-trip ping times:
289
+ ```bash
290
+ amv-train cluster-probe --fleet 192.168.1.101:50052,192.168.1.102:50052,192.168.1.103:50052
291
+ ```
292
+
293
+ #### Step 4: Initiating Distributed Virtual RAM Pipeline Training
294
+ Train across the aggregated 44GB virtual RAM pool with zero changes to model architecture:
295
+ ```bash
296
+ # Distributed LLM LoRA Training with GPU Slicing
297
+ amv-train train \
298
+ --model tiny-transformer \
299
+ --data ./large_corpus.txt \
300
+ --output ./cluster_adapter.safetensors \
301
+ --virtual-ram-pool 192.168.1.101:50052,192.168.1.102:50052,192.168.1.103:50052 \
302
+ --epochs 5 \
303
+ --vocab-slice 4096 \
304
+ --chunk-layers 2 \
305
+ --backend vulkan
306
+
307
+ # Distributed Image Diffusion LoRA Training
308
+ amv-train diffusion-train \
309
+ --image-dir ./dataset \
310
+ --output ./diff_cluster_adapter.safetensors \
311
+ --virtual-ram-pool 192.168.1.101:50052,192.168.1.102:50052 \
312
+ --epochs 5 \
313
+ --backend vulkan
314
+ ```
315
+
316
+ #### Step 5: MasterTunnel Cryptographic Loopback Security
317
+ When passing sensitive weights and intermediate activations across untrusted Wi-Fi subnets, `amv-train` and `ameva-cluster` automatically spawn an authenticated `MasterTunnel` that wraps all inter-device gRPC/HTTP RPC traffic with an ephemeral SHA-256 cryptographic handshake.
318
+
319
+ ---
320
+
321
+ ## Programmatic SDK Usage
322
+
323
+ ### Python SDK
324
+ ```python
325
+ import amv_train as tt
326
+
327
+ # High-level training interface
328
+ trainer = tt.TermuxTrainer(
329
+ model_type="lora",
330
+ lora_rank=8,
331
+ lora_alpha=16.0,
332
+ backend="vulkan",
333
+ vocab_slice=4096,
334
+ chunk_layers=2
335
+ )
336
+
337
+ metrics = trainer.fit(
338
+ data_path="./corpus.txt",
339
+ epochs=3,
340
+ learning_rate=0.0002,
341
+ output_path="./model_lora.safetensors"
342
+ )
343
+ print(f"Final training loss: {metrics['final_loss']:.4f}")
344
+ ```
345
+
346
+ ### Node.js / TypeScript SDK
347
+ ```typescript
348
+ import { trainDiffusion, trainVision, trainSTT, TermuxTrainer } from 'amv-train';
349
+
350
+ // Asynchronous image diffusion fine-tuning
351
+ const result = await trainDiffusion({
352
+ imageDir: './training_images',
353
+ output: './adapter_diffusion.safetensors',
354
+ prompt: 'photorealistic macro nature photography',
355
+ resolution: 512,
356
+ epochs: 5,
357
+ backend: 'vulkan'
358
+ });
359
+ console.log(`Diffusion training completed with status: ${result.status}`);
360
+ ```
361
+
362
+ ---
363
+
364
+ ## Target Runtime Compatibility & Adapter Hub
365
+
366
+ All adapters generated by AMV-Train are zero-conversion artifacts accompanied by a standardized `_config.json` sidecar.
367
+
368
+ | Target Runtime | Adapter Format | Companion Sidecar | Validation Status |
369
+ | :--- | :--- | :--- | :--- |
370
+ | **ComfyUI / Diffusers** | `.safetensors` (UNet CrossAttention) | `adapter_diffusion_config.json` | Validated by automated checks |
371
+ | **llama.cpp / GGUF** | `.safetensors` / GGUF LoRA | `adapter_llm_config.json` | Validated by automated checks |
372
+ | **amv-vision** | `.safetensors` (Multimodal Projector) | `adapter_vision_config.json` | Validated by automated checks |
373
+ | **amv-stt** | `.safetensors` (Whisper Attention) | `adapter_stt_config.json` | Validated by automated checks |
374
+ | **amv-tts** | `.safetensors` (Speaker Style) | `adapter_tts_config.json` | Validated by automated checks |
375
+ | **bitnet.cpp** | `.safetensors` (Ternary 1.58-bit) | `bitnet_config.json` | Validated by automated checks |
376
+
377
+ ---
378
+
379
+ ## Official Documentation & Foundation Resources
380
+
381
+ - [Official Architecture & API Reference](https://uno-km.vercel.app/lib/train/)
382
+ - [Ecosystem Metrics & Registry Stats](https://uno-km.vercel.app/foundation/metrics)
383
+ - [AMEVA Open-Source Foundation Portal](https://uno-km.vercel.app/foundation/index.html)
384
+
385
+ ---
386
+
387
+ ## Open-Source Attribution & License
388
+
389
+ Licensed under the **Apache-2.0 License**. Copyright (c) 2026 Eunho Kim ([@uno-km](https://github.com/uno-km)) and the AMEVA Open-Source Foundation.
package/README.pypi.md ADDED
@@ -0,0 +1,90 @@
1
+ # AMV-Train (Python)
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/amv-train.svg?style=flat-square&color=0369a1)](https://pypi.org/project/amv-train/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/amv-train.svg?style=flat-square)](https://pypi.org/project/amv-train/)
5
+ [![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/amv-train)
6
+
7
+ > Unified Multimodal On-Device Deep Learning & LoRA Training Framework for Android Termux with 6-Modality Adapters (LLM, Diffusion, VLM, STT, TTS, BitNet), GPU Slicing, and 44GB Disaggregated Cluster Virtual RAM Pooling.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ pip install amv-train
13
+
14
+ # For multi-device distributed 44GB Virtual RAM Pooling (Required):
15
+ pip install ameva-cluster
16
+ ```
17
+
18
+ ## Python Quickstart
19
+
20
+ ```python
21
+ import amv_train as tt
22
+
23
+ # 1. Diffusion LoRA Training
24
+ tt.diffusion.train_diffusion_lora(
25
+ image_dir="./training_images",
26
+ output_path="./adapter_diffusion.safetensors",
27
+ prompt="industrial technical illustration",
28
+ resolution=512,
29
+ epochs=5,
30
+ lr=0.0001,
31
+ rank=8,
32
+ backend="vulkan"
33
+ )
34
+
35
+ # 2. Vision VLM LoRA Training
36
+ tt.vision.train_vision_vlm_lora(
37
+ data_source="./vlm_dataset.jsonl",
38
+ output_path="./adapter_vision.safetensors",
39
+ epochs=3,
40
+ backend="vulkan"
41
+ )
42
+ ```
43
+
44
+ ## AMEVA Cluster Multi-Device Virtual RAM Manual
45
+ To train models exceeding single-device physical memory across multiple Android smartphones:
46
+ ```bash
47
+ # Step 1: Run worker on contributor phones (e.g. S21, S20, A53)
48
+ ameva-cluster worker --port 50052 --guard-band 300
49
+
50
+ # Step 2: Probe fleet from coordinator phone (e.g. S25)
51
+ amv-train cluster-probe --fleet 192.168.1.101:50052,192.168.1.102:50052
52
+
53
+ # Step 3: Run distributed pipeline training on aggregated 44GB virtual RAM pool
54
+ amv-train train --model tiny-transformer --data ./corpus.txt \
55
+ --virtual-ram-pool 192.168.1.101:50052,192.168.1.102:50052 \
56
+ --vocab-slice 4096 --chunk-layers 2 --backend vulkan
57
+ ```
58
+
59
+ ## CLI Usage
60
+
61
+ ```bash
62
+ # Diffusion LoRA
63
+ amv-train diffusion-train --image-dir ./images --output ./adapter.safetensors --epochs 5
64
+
65
+ # Vision VLM LoRA
66
+ amv-train vision-train --data ./vlm.jsonl --output ./vlm_adapter.safetensors --epochs 3
67
+
68
+ # Whisper STT LoRA
69
+ amv-train stt-train --data ./audio.jsonl --output ./stt_adapter.safetensors --epochs 4
70
+
71
+ # TTS Style LoRA
72
+ amv-train tts-train --data ./speech.jsonl --output ./tts_adapter.safetensors --epochs 5
73
+
74
+ # LLM LoRA with GPU Slicing
75
+ amv-train train --model tiny-transformer --data ./corpus.txt --vocab-slice 4096 --chunk-layers 2
76
+ ```
77
+
78
+ ## Documentation & Repository
79
+ - Official Documentation: https://uno-km.vercel.app/lib/train/
80
+ - GitHub Repository: https://github.com/uno-km/amv-train
81
+
82
+ ## License
83
+ Apache-2.0 License. Copyright (c) 2026 Eunho Kim (@uno-km).
84
+
85
+
86
+ ## What's New in v2.1.0 — Vulkan Backend Line-Break Syntax Patch & DAG Autograd Hardening
87
+
88
+ - Fixed CRLF line-break syntax error in Vulkan compute shader backend.
89
+ - Hardened SafeTensors zero-copy memory mapping and LoRA gradient accumulation.
90
+ - Standardized Apache-2.0 SPDX license headers and published npm package v2.1.0.