Project-Chronos 0.1.1__tar.gz → 0.2.0__tar.gz

{project_chronos-0.1.1 → project_chronos-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Project_Chronos
-Version: 0.1.1
+Version: 0.2.0
 Summary: On-device low-latency lookahead dual-layer MoE inference — Lookahead Routing + Async Prefetch + Hybrid Attention
 License-Expression: Apache-2.0
 Keywords: llm,moe,inference,lookahead-routing,hybrid-attention,edge-ai
@@ -37,7 +37,7 @@ Dynamic: requires-python
 
 **A storage-aware MoE stack built for SSD+DRAM hybrid inference, with a full six-stage training pipeline.**
 
-[![PyPI](https://img.shields.io/pypi/v/project-chronos)](https://pypi.org/project/project-chronos/)
+[![PyPI](https://img.shields.io/pypi/v/Project_Chronos)](https://pypi.org/project/Project_Chronos/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
 
@@ -139,7 +139,7 @@ Even the worst case does not hard-stop generation:
 output = avail[i] * expert_output + (1.0 - avail[i]) * shared_expert_output
 ```
 
-The shared expert is always resident, so generation continues while the missing expert finishes loading in the background. Quality degrades smoothly and recovers automatically once the expert becomes available.
+The shared expert is always resident, so generation continues while the missing expert finishes loading in the background. For exact lazy/offload comparison modes, Chronos synchronously materializes only the selected missing expert and evicts low-LRU experts to stay inside the resident budget; it does not silently full-load all experts. Quality degrades smoothly only when fallback mode is explicitly enabled.
 
 ---
 
@@ -222,6 +222,29 @@ flowchart LR
 | 5 GRPO | `train_chronos_grpo.py` | `PG * A - beta * KL` with `ToyReward` or pluggable `LMRewardModel` | 0.10 |
 | 6 Distill | `train_chronos_distill.py` | `alpha * T^2 * KL(student || teacher) + (1 - alpha) * CE` | 0.05 |
 
+Training dtype and resource policy:
+
+- `--dtype auto` is the default. MPS/MLX resolve to BF16-first for training stability, CUDA/XPU resolve to FP16, and CPU resolves to FP32 unless `--dtype float16` or `--dtype bfloat16` is set explicitly.
+- CPU training configures PyTorch to use physical cores by default. Override with `--cpu_threads` or `--cpu_budget_percent`.
+- On macOS, MPS/MLX training forces DataLoader workers to `0` by default to avoid Metal command-buffer crashes from multiprocessing. CPU/CUDA still use worker processes; advanced users can override the guard with `CHRONOS_ALLOW_METAL_DATALOADER_WORKERS=1`.
+- Native MLX training pushes UI logs, scalar readouts, and chart points every `log_interval` steps, and Web UI Stop is checked at each batch boundary.
+- The Web UI writes a warning-only `<checkpoint>.verify.json` after each stage. It checks no-mask vs all-available MoE parity and, on Apple Silicon, MLX prefill logits against the PyTorch CPU baseline.
+
+Native MLX training is a separate Apple Silicon backend, not `torch.to("mlx")`.
+The six-stage MLX trainer mirrors the PyTorch loss stack in `chronos.mlx.*`:
+masked CE, DPO/ORPO/GRPO/distillation losses, load balance, temporal locality,
+lookahead soft-target supervision, lookahead top-k hit loss, and router KL
+anchor. Numerically sensitive pieces run in FP32 even when model weights use
+BF16/FP16, which is why `auto` prefers BF16 on MLX/MPS: FP16 has too little
+exponent range for router softmax, CE, and Adam moments on small unstable
+training runs.
+
+The MLX Web UI trainer reports the same fields as CPU/MPS training:
+step/loss/steps-per-second/ETA, checkpoint-save events, stop events, and
+verify results. Stop is cooperative at batch boundaries and save intervals
+write a valid `.pth` plus sibling `.config.json`, so MLX stages can resume or
+feed the PyTorch/export pipeline.
+
 The full six-stage comparison harness lives in `tools/compare_minimind_chronos_v3.py`.
 
 ---
@@ -254,9 +277,36 @@ d.describe()    # human-readable capability summary
 - **First-class backends for training and inference**: `cpu`, `mps`, `cuda`, `mlx`
 - **Inference-only / experimental**: `vulkan` when PyTorch was custom-built with `USE_VULKAN=ON`
 - **Third-party extension hook**: `opencl`, via `chronos/backend/ext/opencl.py:PROBE()`
+- **Apple Silicon policy**: inference auto still prefers MLX; training keeps MLX on the native `chronos.mlx.*` path instead of calling `torch.model.to("mlx")`.
 
 Honest note: upstream PyTorch does not ship a real OpenCL backend, and Vulkan support is still niche. Chronos provides a dispatcher seam so external integrations can plug in cleanly without touching core code.
 
+### MLX lazy/offload runtime
+
+MLX uses Apple unified memory, so Chronos treats "VRAM" and "RAM" as logical
+tiers rather than physical buses. The native lazy runtime still enforces the
+same offload contract as CUDA/MPS/CPU:
+
+- **Hot slots** hold only the execution-budget experts materialized as live
+  MLX modules.
+- **Warm cache** holds a bounded prediction buffer loaded from `.ctsr`
+  safetensors, never a hidden copy of every expert.
+- **Cold storage** is the checkpoint/export reader or per-expert cluster cache.
+  In lazy mode, live experts are replaced by placeholders after cache creation;
+  Chronos does not keep a `_saved_live` full-expert repair cache.
+- Lookahead predictions are queued into the warm cache and only promoted when
+  ready. A true miss synchronously materializes the selected expert only; it
+  does not full-load the model.
+- MLX attention dynamically grows RoPE lookup tables past
+  `max_position_embeddings`, so long prompts plus decode do not fail at token
+  257/513/etc.
+
+Inference compare/sweep reports real hot/warm counts, resident hit rate,
+prediction hit rate, sync SSD loads, MLX active/cache/peak memory, process RSS,
+prefill/decode time, and tokens/sec. A lazy run is not considered
+offload-ready unless deterministic exact-lazy output matches full-DRAM output
+and fallback weight stays zero.
+
 ---
 
 ## Hugging Face and vLLM compatibility (M5)
@@ -339,7 +389,7 @@ All lambda terms are searchable with Optuna TPE, together with structural hyperp
 ## Installation
 
 ```bash
-pip install project-chronos
+pip install Project_Chronos
 ```
 
 Or from source:
@@ -353,7 +403,7 @@ pip install -e ".[dev]"
 **MLX (Apple Silicon):**
 
 ```bash
-pip install "project-chronos[mlx]"
+pip install "Project_Chronos[mlx]"
 ```
 
 **vLLM serving (optional, Linux + CUDA only):**
@@ -372,7 +422,7 @@ pip install vllm
 
 ## Quick start
 
-### Web UI (M6: 7 tabs, 4 languages)
+### Web UI (M6: 8 tabs, 4 languages)
 
 ```bash
 chronos-ui
@@ -386,12 +436,31 @@ Tabs included:
 - `Train` with its own `data_path`
 - `6-Stage Pipeline` with per-stage dataset paths
 - `Inference`
-- `Benchmark` with Markdown table + bar plot
+- `Export` for FP16/Q8_0 safetensors and GGUF deployment artifacts
+- `Benchmark` with Markdown table + comparison plots
 - `Auto-Tune` with persistent logs and one-click `Apply Best -> Config`
 - `IO Monitor`
 
 Built-in i18n: `zh-Hans`, `zh-Hant`, `en`, `ja`
 
+### Deployment export
+
+```bash
+chronos export \
+    --model_path ./out/sft_384_moe.pth \
+    --output_dir ./exports/sft_384 \
+    --formats fp16-safetensors q8_0-safetensors fp16-gguf q8_0-gguf
+```
+
+Exports include `config.json`, `chronos_export_manifest.json`, and Chronos
+metadata for MoE top-k, shared fallback experts, lookahead router, hybrid
+attention, and optional expert-cache layout. Chronos can load exported
+`safetensors`/`GGUF` artifacts through its native lazy expert loader.
+
+Compatibility note: the GGUF files use `general.architecture=chronos`. Stock
+Ollama/llama.cpp builds need a Chronos architecture adapter to execute them
+correctly; Chronos is not a LLaMA tensor-layout clone.
+
 ### Stage 1: pretrain
 
 ```bash
@@ -421,6 +490,32 @@ python train_chronos_distill.py \
     --alpha 0.7 --temperature 4.0
 ```
 
+### Checkpoint and offload diagnostics
+
+Every new `.pth` checkpoint writes a sibling `*.config.json` with the MoE
+topology that cannot be recovered from tensor shapes, including
+`num_experts_per_tok`. Use the diagnostic command to verify chat-template
+generation, no-mask vs all-available masked drift, cold shared fallback,
+LookaheadRouter prediction quality, and SSD/RAM/VRAM offload stats.
+
+```bash
+python diagnose_checkpoint.py \
+    --model_path ./out/sft_384_moe.pth \
+    --config_path ./chronos_config.json \
+    --sft_data ./Dataset/sft_t2t.jsonl \
+    --mlx_parity \
+    --device cpu
+
+# or through the unified CLI:
+chronos diagnose --model_path ./out/sft_384_moe.pth --config_path ./chronos_config.json
+```
+
+For backend speed and dtype sanity checks:
+
+```bash
+python benchmark_training_backends.py --backends cpu mps mlx --dtypes auto bfloat16 float16 --steps 2
+```
+
 ### End-to-end comparison (minimind vs Chronos)
 
 ```bash

{project_chronos-0.1.1 → project_chronos-0.2.0}/Project_Chronos.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Project_Chronos
-Version: 0.1.1
+Version: 0.2.0
 Summary: On-device low-latency lookahead dual-layer MoE inference — Lookahead Routing + Async Prefetch + Hybrid Attention
 License-Expression: Apache-2.0
 Keywords: llm,moe,inference,lookahead-routing,hybrid-attention,edge-ai
@@ -37,7 +37,7 @@ Dynamic: requires-python
 
 **A storage-aware MoE stack built for SSD+DRAM hybrid inference, with a full six-stage training pipeline.**
 
-[![PyPI](https://img.shields.io/pypi/v/project-chronos)](https://pypi.org/project/project-chronos/)
+[![PyPI](https://img.shields.io/pypi/v/Project_Chronos)](https://pypi.org/project/Project_Chronos/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
 
@@ -139,7 +139,7 @@ Even the worst case does not hard-stop generation:
 output = avail[i] * expert_output + (1.0 - avail[i]) * shared_expert_output
 ```
 
-The shared expert is always resident, so generation continues while the missing expert finishes loading in the background. Quality degrades smoothly and recovers automatically once the expert becomes available.
+The shared expert is always resident, so generation continues while the missing expert finishes loading in the background. For exact lazy/offload comparison modes, Chronos synchronously materializes only the selected missing expert and evicts low-LRU experts to stay inside the resident budget; it does not silently full-load all experts. Quality degrades smoothly only when fallback mode is explicitly enabled.
 
 ---
 
@@ -222,6 +222,29 @@ flowchart LR
 | 5 GRPO | `train_chronos_grpo.py` | `PG * A - beta * KL` with `ToyReward` or pluggable `LMRewardModel` | 0.10 |
 | 6 Distill | `train_chronos_distill.py` | `alpha * T^2 * KL(student || teacher) + (1 - alpha) * CE` | 0.05 |
 
+Training dtype and resource policy:
+
+- `--dtype auto` is the default. MPS/MLX resolve to BF16-first for training stability, CUDA/XPU resolve to FP16, and CPU resolves to FP32 unless `--dtype float16` or `--dtype bfloat16` is set explicitly.
+- CPU training configures PyTorch to use physical cores by default. Override with `--cpu_threads` or `--cpu_budget_percent`.
+- On macOS, MPS/MLX training forces DataLoader workers to `0` by default to avoid Metal command-buffer crashes from multiprocessing. CPU/CUDA still use worker processes; advanced users can override the guard with `CHRONOS_ALLOW_METAL_DATALOADER_WORKERS=1`.
+- Native MLX training pushes UI logs, scalar readouts, and chart points every `log_interval` steps, and Web UI Stop is checked at each batch boundary.
+- The Web UI writes a warning-only `<checkpoint>.verify.json` after each stage. It checks no-mask vs all-available MoE parity and, on Apple Silicon, MLX prefill logits against the PyTorch CPU baseline.
+
+Native MLX training is a separate Apple Silicon backend, not `torch.to("mlx")`.
+The six-stage MLX trainer mirrors the PyTorch loss stack in `chronos.mlx.*`:
+masked CE, DPO/ORPO/GRPO/distillation losses, load balance, temporal locality,
+lookahead soft-target supervision, lookahead top-k hit loss, and router KL
+anchor. Numerically sensitive pieces run in FP32 even when model weights use
+BF16/FP16, which is why `auto` prefers BF16 on MLX/MPS: FP16 has too little
+exponent range for router softmax, CE, and Adam moments on small unstable
+training runs.
+
+The MLX Web UI trainer reports the same fields as CPU/MPS training:
+step/loss/steps-per-second/ETA, checkpoint-save events, stop events, and
+verify results. Stop is cooperative at batch boundaries and save intervals
+write a valid `.pth` plus sibling `.config.json`, so MLX stages can resume or
+feed the PyTorch/export pipeline.
+
 The full six-stage comparison harness lives in `tools/compare_minimind_chronos_v3.py`.
 
 ---
@@ -254,9 +277,36 @@ d.describe()    # human-readable capability summary
 - **First-class backends for training and inference**: `cpu`, `mps`, `cuda`, `mlx`
 - **Inference-only / experimental**: `vulkan` when PyTorch was custom-built with `USE_VULKAN=ON`
 - **Third-party extension hook**: `opencl`, via `chronos/backend/ext/opencl.py:PROBE()`
+- **Apple Silicon policy**: inference auto still prefers MLX; training keeps MLX on the native `chronos.mlx.*` path instead of calling `torch.model.to("mlx")`.
 
 Honest note: upstream PyTorch does not ship a real OpenCL backend, and Vulkan support is still niche. Chronos provides a dispatcher seam so external integrations can plug in cleanly without touching core code.
 
+### MLX lazy/offload runtime
+
+MLX uses Apple unified memory, so Chronos treats "VRAM" and "RAM" as logical
+tiers rather than physical buses. The native lazy runtime still enforces the
+same offload contract as CUDA/MPS/CPU:
+
+- **Hot slots** hold only the execution-budget experts materialized as live
+  MLX modules.
+- **Warm cache** holds a bounded prediction buffer loaded from `.ctsr`
+  safetensors, never a hidden copy of every expert.
+- **Cold storage** is the checkpoint/export reader or per-expert cluster cache.
+  In lazy mode, live experts are replaced by placeholders after cache creation;
+  Chronos does not keep a `_saved_live` full-expert repair cache.
+- Lookahead predictions are queued into the warm cache and only promoted when
+  ready. A true miss synchronously materializes the selected expert only; it
+  does not full-load the model.
+- MLX attention dynamically grows RoPE lookup tables past
+  `max_position_embeddings`, so long prompts plus decode do not fail at token
+  257/513/etc.
+
+Inference compare/sweep reports real hot/warm counts, resident hit rate,
+prediction hit rate, sync SSD loads, MLX active/cache/peak memory, process RSS,
+prefill/decode time, and tokens/sec. A lazy run is not considered
+offload-ready unless deterministic exact-lazy output matches full-DRAM output
+and fallback weight stays zero.
+
 ---
 
 ## Hugging Face and vLLM compatibility (M5)
@@ -339,7 +389,7 @@ All lambda terms are searchable with Optuna TPE, together with structural hyperp
 ## Installation
 
 ```bash
-pip install project-chronos
+pip install Project_Chronos
 ```
 
 Or from source:
@@ -353,7 +403,7 @@ pip install -e ".[dev]"
 **MLX (Apple Silicon):**
 
 ```bash
-pip install "project-chronos[mlx]"
+pip install "Project_Chronos[mlx]"
 ```
 
 **vLLM serving (optional, Linux + CUDA only):**
@@ -372,7 +422,7 @@ pip install vllm
 
 ## Quick start
 
-### Web UI (M6: 7 tabs, 4 languages)
+### Web UI (M6: 8 tabs, 4 languages)
 
 ```bash
 chronos-ui
@@ -386,12 +436,31 @@ Tabs included:
 - `Train` with its own `data_path`
 - `6-Stage Pipeline` with per-stage dataset paths
 - `Inference`
-- `Benchmark` with Markdown table + bar plot
+- `Export` for FP16/Q8_0 safetensors and GGUF deployment artifacts
+- `Benchmark` with Markdown table + comparison plots
 - `Auto-Tune` with persistent logs and one-click `Apply Best -> Config`
 - `IO Monitor`
 
 Built-in i18n: `zh-Hans`, `zh-Hant`, `en`, `ja`
 
+### Deployment export
+
+```bash
+chronos export \
+    --model_path ./out/sft_384_moe.pth \
+    --output_dir ./exports/sft_384 \
+    --formats fp16-safetensors q8_0-safetensors fp16-gguf q8_0-gguf
+```
+
+Exports include `config.json`, `chronos_export_manifest.json`, and Chronos
+metadata for MoE top-k, shared fallback experts, lookahead router, hybrid
+attention, and optional expert-cache layout. Chronos can load exported
+`safetensors`/`GGUF` artifacts through its native lazy expert loader.
+
+Compatibility note: the GGUF files use `general.architecture=chronos`. Stock
+Ollama/llama.cpp builds need a Chronos architecture adapter to execute them
+correctly; Chronos is not a LLaMA tensor-layout clone.
+
 ### Stage 1: pretrain
 
 ```bash
@@ -421,6 +490,32 @@ python train_chronos_distill.py \
     --alpha 0.7 --temperature 4.0
 ```
 
+### Checkpoint and offload diagnostics
+
+Every new `.pth` checkpoint writes a sibling `*.config.json` with the MoE
+topology that cannot be recovered from tensor shapes, including
+`num_experts_per_tok`. Use the diagnostic command to verify chat-template
+generation, no-mask vs all-available masked drift, cold shared fallback,
+LookaheadRouter prediction quality, and SSD/RAM/VRAM offload stats.
+
+```bash
+python diagnose_checkpoint.py \
+    --model_path ./out/sft_384_moe.pth \
+    --config_path ./chronos_config.json \
+    --sft_data ./Dataset/sft_t2t.jsonl \
+    --mlx_parity \
+    --device cpu
+
+# or through the unified CLI:
+chronos diagnose --model_path ./out/sft_384_moe.pth --config_path ./chronos_config.json
+```
+
+For backend speed and dtype sanity checks:
+
+```bash
+python benchmark_training_backends.py --backends cpu mps mlx --dtypes auto bfloat16 float16 --steps 2
+```
+
 ### End-to-end comparison (minimind vs Chronos)
 
 ```bash

{project_chronos-0.1.1 → project_chronos-0.2.0}/Project_Chronos.egg-info/SOURCES.txt

@@ -21,8 +21,11 @@ chronos/_backend_legacy.py
 chronos/app.py
 chronos/cli.py
 chronos/deps.py
+chronos/export.py
+chronos/verify.py
 chronos/backend/__init__.py
 chronos/backend/dispatcher.py
+chronos/backend/mac_diagnostics.py
 chronos/backend/ext/__init__.py
 chronos/backend/ext/opencl.py
 chronos/data/__init__.py
@@ -42,7 +45,11 @@ chronos/mlx/expert_store.py
 chronos/mlx/inference.py
 chronos/mlx/model.py
 chronos/mlx/moe.py
+chronos/mlx/training/__init__.py
+chronos/mlx/training/io.py
+chronos/mlx/training/trainer.py
 chronos/model/__init__.py
+chronos/model/checkpoint.py
 chronos/model/config.py
 chronos/model/hf_io.py
 chronos/model/hybrid_attention.py
@@ -62,6 +69,7 @@ chronos/serving/__init__.py
 chronos/serving/vllm_adapter.py
 chronos/trainer/__init__.py
 chronos/trainer/chronos_trainer.py
+chronos/trainer/device_utils.py
 chronos/trainer/distill_trainer.py
 chronos/trainer/dpo_trainer.py
 chronos/trainer/grpo_trainer.py
@@ -70,6 +78,7 @@ chronos/trainer/optim_utils.py
 chronos/trainer/orpo_trainer.py
 chronos/trainer/reward.py
 chronos/trainer/sft_trainer.py
+chronos/trainer/stage_utils.py
 chronos/tuning/__init__.py
 chronos/tuning/_base_tuner.py
 chronos/tuning/chronos_auto_tuner.py
@@ -85,6 +94,7 @@ ui/tabs/autotune_tab.py
 ui/tabs/benchmark_tab.py
 ui/tabs/config_tab.py
 ui/tabs/data_tab.py
+ui/tabs/export_tab.py
 ui/tabs/inference_tab.py
 ui/tabs/iomon_tab.py
 ui/tabs/pipeline_tab.py

{project_chronos-0.1.1 → project_chronos-0.2.0}/README.md

@@ -2,7 +2,7 @@
 
 **A storage-aware MoE stack built for SSD+DRAM hybrid inference, with a full six-stage training pipeline.**
 
-[![PyPI](https://img.shields.io/pypi/v/project-chronos)](https://pypi.org/project/project-chronos/)
+[![PyPI](https://img.shields.io/pypi/v/Project_Chronos)](https://pypi.org/project/Project_Chronos/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
 
@@ -104,7 +104,7 @@ Even the worst case does not hard-stop generation:
 output = avail[i] * expert_output + (1.0 - avail[i]) * shared_expert_output
 ```
 
-The shared expert is always resident, so generation continues while the missing expert finishes loading in the background. Quality degrades smoothly and recovers automatically once the expert becomes available.
+The shared expert is always resident, so generation continues while the missing expert finishes loading in the background. For exact lazy/offload comparison modes, Chronos synchronously materializes only the selected missing expert and evicts low-LRU experts to stay inside the resident budget; it does not silently full-load all experts. Quality degrades smoothly only when fallback mode is explicitly enabled.
 
 ---
 
@@ -187,6 +187,29 @@ flowchart LR
 | 5 GRPO | `train_chronos_grpo.py` | `PG * A - beta * KL` with `ToyReward` or pluggable `LMRewardModel` | 0.10 |
 | 6 Distill | `train_chronos_distill.py` | `alpha * T^2 * KL(student || teacher) + (1 - alpha) * CE` | 0.05 |
 
+Training dtype and resource policy:
+
+- `--dtype auto` is the default. MPS/MLX resolve to BF16-first for training stability, CUDA/XPU resolve to FP16, and CPU resolves to FP32 unless `--dtype float16` or `--dtype bfloat16` is set explicitly.
+- CPU training configures PyTorch to use physical cores by default. Override with `--cpu_threads` or `--cpu_budget_percent`.
+- On macOS, MPS/MLX training forces DataLoader workers to `0` by default to avoid Metal command-buffer crashes from multiprocessing. CPU/CUDA still use worker processes; advanced users can override the guard with `CHRONOS_ALLOW_METAL_DATALOADER_WORKERS=1`.
+- Native MLX training pushes UI logs, scalar readouts, and chart points every `log_interval` steps, and Web UI Stop is checked at each batch boundary.
+- The Web UI writes a warning-only `<checkpoint>.verify.json` after each stage. It checks no-mask vs all-available MoE parity and, on Apple Silicon, MLX prefill logits against the PyTorch CPU baseline.
+
+Native MLX training is a separate Apple Silicon backend, not `torch.to("mlx")`.
+The six-stage MLX trainer mirrors the PyTorch loss stack in `chronos.mlx.*`:
+masked CE, DPO/ORPO/GRPO/distillation losses, load balance, temporal locality,
+lookahead soft-target supervision, lookahead top-k hit loss, and router KL
+anchor. Numerically sensitive pieces run in FP32 even when model weights use
+BF16/FP16, which is why `auto` prefers BF16 on MLX/MPS: FP16 has too little
+exponent range for router softmax, CE, and Adam moments on small unstable
+training runs.
+
+The MLX Web UI trainer reports the same fields as CPU/MPS training:
+step/loss/steps-per-second/ETA, checkpoint-save events, stop events, and
+verify results. Stop is cooperative at batch boundaries and save intervals
+write a valid `.pth` plus sibling `.config.json`, so MLX stages can resume or
+feed the PyTorch/export pipeline.
+
 The full six-stage comparison harness lives in `tools/compare_minimind_chronos_v3.py`.
 
 ---
@@ -219,9 +242,36 @@ d.describe()    # human-readable capability summary
 - **First-class backends for training and inference**: `cpu`, `mps`, `cuda`, `mlx`
 - **Inference-only / experimental**: `vulkan` when PyTorch was custom-built with `USE_VULKAN=ON`
 - **Third-party extension hook**: `opencl`, via `chronos/backend/ext/opencl.py:PROBE()`
+- **Apple Silicon policy**: inference auto still prefers MLX; training keeps MLX on the native `chronos.mlx.*` path instead of calling `torch.model.to("mlx")`.
 
 Honest note: upstream PyTorch does not ship a real OpenCL backend, and Vulkan support is still niche. Chronos provides a dispatcher seam so external integrations can plug in cleanly without touching core code.
 
+### MLX lazy/offload runtime
+
+MLX uses Apple unified memory, so Chronos treats "VRAM" and "RAM" as logical
+tiers rather than physical buses. The native lazy runtime still enforces the
+same offload contract as CUDA/MPS/CPU:
+
+- **Hot slots** hold only the execution-budget experts materialized as live
+  MLX modules.
+- **Warm cache** holds a bounded prediction buffer loaded from `.ctsr`
+  safetensors, never a hidden copy of every expert.
+- **Cold storage** is the checkpoint/export reader or per-expert cluster cache.
+  In lazy mode, live experts are replaced by placeholders after cache creation;
+  Chronos does not keep a `_saved_live` full-expert repair cache.
+- Lookahead predictions are queued into the warm cache and only promoted when
+  ready. A true miss synchronously materializes the selected expert only; it
+  does not full-load the model.
+- MLX attention dynamically grows RoPE lookup tables past
+  `max_position_embeddings`, so long prompts plus decode do not fail at token
+  257/513/etc.
+
+Inference compare/sweep reports real hot/warm counts, resident hit rate,
+prediction hit rate, sync SSD loads, MLX active/cache/peak memory, process RSS,
+prefill/decode time, and tokens/sec. A lazy run is not considered
+offload-ready unless deterministic exact-lazy output matches full-DRAM output
+and fallback weight stays zero.
+
 ---
 
 ## Hugging Face and vLLM compatibility (M5)
@@ -304,7 +354,7 @@ All lambda terms are searchable with Optuna TPE, together with structural hyperp
 ## Installation
 
 ```bash
-pip install project-chronos
+pip install Project_Chronos
 ```
 
 Or from source:
@@ -318,7 +368,7 @@ pip install -e ".[dev]"
 **MLX (Apple Silicon):**
 
 ```bash
-pip install "project-chronos[mlx]"
+pip install "Project_Chronos[mlx]"
 ```
 
 **vLLM serving (optional, Linux + CUDA only):**
@@ -337,7 +387,7 @@ pip install vllm
 
 ## Quick start
 
-### Web UI (M6: 7 tabs, 4 languages)
+### Web UI (M6: 8 tabs, 4 languages)
 
 ```bash
 chronos-ui
@@ -351,12 +401,31 @@ Tabs included:
 - `Train` with its own `data_path`
 - `6-Stage Pipeline` with per-stage dataset paths
 - `Inference`
-- `Benchmark` with Markdown table + bar plot
+- `Export` for FP16/Q8_0 safetensors and GGUF deployment artifacts
+- `Benchmark` with Markdown table + comparison plots
 - `Auto-Tune` with persistent logs and one-click `Apply Best -> Config`
 - `IO Monitor`
 
 Built-in i18n: `zh-Hans`, `zh-Hant`, `en`, `ja`
 
+### Deployment export
+
+```bash
+chronos export \
+    --model_path ./out/sft_384_moe.pth \
+    --output_dir ./exports/sft_384 \
+    --formats fp16-safetensors q8_0-safetensors fp16-gguf q8_0-gguf
+```
+
+Exports include `config.json`, `chronos_export_manifest.json`, and Chronos
+metadata for MoE top-k, shared fallback experts, lookahead router, hybrid
+attention, and optional expert-cache layout. Chronos can load exported
+`safetensors`/`GGUF` artifacts through its native lazy expert loader.
+
+Compatibility note: the GGUF files use `general.architecture=chronos`. Stock
+Ollama/llama.cpp builds need a Chronos architecture adapter to execute them
+correctly; Chronos is not a LLaMA tensor-layout clone.
+
 ### Stage 1: pretrain
 
 ```bash
@@ -386,6 +455,32 @@ python train_chronos_distill.py \
     --alpha 0.7 --temperature 4.0
 ```
 
+### Checkpoint and offload diagnostics
+
+Every new `.pth` checkpoint writes a sibling `*.config.json` with the MoE
+topology that cannot be recovered from tensor shapes, including
+`num_experts_per_tok`. Use the diagnostic command to verify chat-template
+generation, no-mask vs all-available masked drift, cold shared fallback,
+LookaheadRouter prediction quality, and SSD/RAM/VRAM offload stats.
+
+```bash
+python diagnose_checkpoint.py \
+    --model_path ./out/sft_384_moe.pth \
+    --config_path ./chronos_config.json \
+    --sft_data ./Dataset/sft_t2t.jsonl \
+    --mlx_parity \
+    --device cpu
+
+# or through the unified CLI:
+chronos diagnose --model_path ./out/sft_384_moe.pth --config_path ./chronos_config.json
+```
+
+For backend speed and dtype sanity checks:
+
+```bash
+python benchmark_training_backends.py --backends cpu mps mlx --dtypes auto bfloat16 float16 --steps 2
+```
+
 ### End-to-end comparison (minimind vs Chronos)
 
 ```bash

{project_chronos-0.1.1 → project_chronos-0.2.0}/chronos/app.py

@@ -18,6 +18,21 @@ _pkg_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 if _pkg_root not in sys.path:
     sys.path.insert(0, _pkg_root)
 
+from chronos.trainer.device_utils import (
+    configure_cpu_thread_env,
+    configure_cpu_threads,
+    cpu_thread_snapshot,
+)
+
+# Configure CPU thread pools before importing Gradio/UI modules that may pull
+# in numpy/torch-heavy dependencies. Training can still override this from the
+# Config tab, but the process starts from a multi-thread policy instead of a
+# shell-provided OMP_NUM_THREADS=1.
+_BOOT_CPU_THREADS = configure_cpu_thread_env(
+    os.environ.get("CHRONOS_UI_CPU_THREADS", "auto"),
+    budget_percent=os.environ.get("CHRONOS_CPU_BUDGET_PERCENT", 100),
+)
+
 from ui.gradio_compat import gr
 
 import chronos.deps  # auto-bootstrap minimind
@@ -28,6 +43,7 @@ from ui.i18n import (
 from ui.tabs.config_tab    import build_config_tab
 from ui.tabs.train_tab     import build_train_tab
 from ui.tabs.inference_tab import build_inference_tab
+from ui.tabs.export_tab    import build_export_tab
 from ui.tabs.benchmark_tab import build_benchmark_tab
 from ui.tabs.autotune_tab  import build_autotune_tab
 from ui.tabs.iomon_tab     import build_iomon_tab
@@ -85,6 +101,7 @@ def build_app() -> gr.Blocks:
         build_train_tab(config_state, cfg_save_dir)
         build_pipeline_tab()
         build_inference_tab(config_state)
+        build_export_tab()
         build_benchmark_tab()
         build_autotune_tab(config_state, config_inputs)
         build_iomon_tab()
@@ -107,8 +124,18 @@ def main():
     parser.add_argument("--port",  type=int,  default=7860)
     parser.add_argument("--host",  type=str,  default="127.0.0.1")
     parser.add_argument("--share", action="store_true")
+    parser.add_argument("--cpu-threads", default="auto",
+                        help="PyTorch/BLAS CPU threads for the WebUI process.")
+    parser.add_argument("--cpu-budget-percent", type=float, default=100,
+                        help="CPU physical-core budget used when --cpu-threads=auto.")
     args = parser.parse_args()
 
+    threads = configure_cpu_threads(args.cpu_threads, budget_percent=args.cpu_budget_percent)
+    print(
+        f"[Chronos UI] CPU threads configured: {threads} "
+        f"(boot={_BOOT_CPU_THREADS}); {cpu_thread_snapshot()}"
+    )
+
     app = build_app()
     app.launch(
         server_name=args.host,

{project_chronos-0.1.1 → project_chronos-0.2.0}/chronos/backend/__init__.py

@@ -20,6 +20,12 @@ from chronos.backend.dispatcher import (
     AUTO_PRIORITY,
     TRAINING_AUTO_PRIORITY,
 )
+from chronos.backend.mac_diagnostics import (
+    mac_backend_diagnostics,
+    mlx_memory_snapshot,
+    mps_memory_snapshot,
+    rss_snapshot,
+)
 
 # Back-compat shim for the pre-M5 API that code elsewhere still calls.
 from chronos._backend_legacy import build_model, BackendType  # type: ignore
@@ -35,6 +41,7 @@ __all__ = [
     "available", "select", "training_available", "select_training",
     "device_str", "training_device_str", "resolve_training_device",
     "describe", "describe_training",
+    "mac_backend_diagnostics", "mlx_memory_snapshot", "mps_memory_snapshot", "rss_snapshot",
     "AUTO_PRIORITY", "TRAINING_AUTO_PRIORITY",
     "get_backend", "build_model", "BackendType",
 ]