release : v1.3.8

- refactor: 重写 IFD 评估为三层架构，引入 BFD 装箱与自定义 attention mask 批处理打分 - refactor: 重写 HumanEval 评估为函数式流水线，修复测试超时与动态 pass@k - perf: 替换 paged KV cache 为 ContiguousCache，解码所有 group - feat: 新增 ROUGE 评估脚本、JSONL 数据集 store、stream_chat 参数 - fix: 修复 IFD token-set 不对称、SFT position_ids 默认值、文档边界保留
fix: resolve IFD token-set asymmetry and support single-token answers
2026-07-05 19:12:33 +08:00 · 2026-07-05 17:48:26 +08:00 · 2026-07-05 11:41:54 +08:00 · 2026-07-05 11:34:36 +08:00 · 2026-07-05 08:47:30 +08:00 · 2026-07-05 07:58:28 +08:00
54 changed files with 2081 additions and 1014 deletions
@@ -5,8 +5,10 @@
 !*/

 # Allow specific file types and root files
-!*.py
-!*.sh
+!astrai/**/*.py
+!scripts/**/*.py
+!scripts/**/*.sh
+!tests/**/*.py

 # Allow GitHub files
 !/.github/**
@@ -23,7 +23,7 @@ COPY astrai/ ./astrai/
 COPY pyproject.toml .
 RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir . \
-    --extra-index-url https://download.pytorch.org/whl/cu126
+    --extra-index-url https://download.pytorch.org/whl/cu128

 # Production stage
 FROM ubuntu:24.04 AS production
@@ -21,6 +21,7 @@ classDiagram

        class BaseModelConfig {
            +Optional[str] model_type
+            +float neftune_alpha
            +from_file(config_path) Self
            +to_file(config_path)
        }
@@ -58,10 +59,12 @@ classDiagram
            +Optional[int] dim_ffn
            +Optional[int] max_len
            +Optional[float] rope_theta
+            +str attn_type
            +Optional[int] n_heads
            +Optional[int] n_kv_heads
            +Optional[bool] use_qk_norm
            +Optional[bool] use_gated_attention
+            +str ffn_type
            +Optional[dict] rope_scaling
            +Optional[str] pooling_type
            +Optional[bool] normalize_embeddings
@@ -118,7 +121,7 @@ classDiagram
            +float max_grad_norm
            +list gradient_checkpointing_modules
            +int start_epoch
-            +int start_batch
+            +int start_samples
            +str ckpt_dir
            +int ckpt_interval
            +str log_dir
@@ -136,7 +139,9 @@ classDiagram
            +str start_method
            +str device_type
            +Optional[Dataset] val_dataset
+            +Optional[float] val_split
            +int val_step
+            +float neftune_alpha
            +str parallel_mode
            +dict executor_kwargs
            +dict extra_kwargs
@@ -215,12 +220,13 @@ classDiagram
        class Checkpoint {
            +dict state_dict
            +int epoch
-            +int iteration
+            +int consumed_samples
            +dict extra
            +dict meta
            +dict config
            +save(save_dir)
            +load(save_dir, broadcast) Checkpoint
+            +load_any(save_dir, broadcast) Optional[Checkpoint]
        }
    }

@@ -350,7 +356,9 @@ classDiagram

        class Embedding {
            +Parameter weight
+            +float neftune_noise_alpha
            +forward(x) Tensor
+            +set_neftune_alpha(alpha)
        }
    }

@@ -407,7 +415,9 @@ classDiagram
            +Dict _entries
            +register(name) decorator
            +create(name, *args, **kwargs) T
+            +get_component_class(name) Type
            +list_registered() list
+            +is_registered(name) bool
        }

        class MaskBuilderFactory {
@@ -436,13 +446,15 @@ classDiagram
            +dict model_config
            +BaseExecutor executor
            +int epoch
-            +int iteration
+            +int consumed_samples
            +float loss
+            +float grad_norm
            +DataLoader val_dataloader
            +float val_loss
            +int world_size
            +int rank
            +dict kwargs
+            +optimizer_step() int
        }

        class TrainContextBuilder {
@@ -594,18 +606,6 @@ classDiagram
            +create(name, **kwargs) TrainCallback
        }

-        class Muon {
-            +float lr
-            +float momentum
-            +float weight_decay
-            +bool nesterov
-            +int ns_steps
-            +Optional[float] adamw_lr
-            +tuple adamw_betas
-            +float adamw_eps
-            +float adamw_wd
-            +step(closure) Optional[float]
-        }
    }

    namespace inference {
@@ -810,7 +810,9 @@ classDiagram

        class ChatMessage {
            +str role
-            +str content
+            +Optional[str] content
+            +Optional[List[Dict]] tool_calls
+            +Optional[str] tool_call_id
        }

        class ChatCompletionRequest {
@@ -827,6 +829,8 @@ classDiagram
            +Optional[float] frequency_penalty
            +Optional[Dict[int, float]] logit_bias
            +Optional[str] user
+            +Optional[List[ToolDef]] tools
+            +Optional[Union[str, Dict]] tool_choice
        }

        class AnthropicMessage {
@@ -850,7 +854,7 @@ classDiagram
            <<abstract>>
            +prepare(request, engine) Tuple[str, GenContext, List[str]]
            +format_stream_start(ctx) List[str]
-            +format_chunk(token) str
+            +format_chunk(token) List[str]
            +format_stream_end(ctx, stop) List[str]
            +format_response(ctx, content, stop) Dict
        }
@@ -858,7 +862,7 @@ classDiagram
        class OpenAIResponseBuilder {
            +prepare(request, engine) Tuple
            +format_stream_start(ctx) List[str]
-            +format_chunk(token) str
+            +format_chunk(token) List[str]
            +format_stream_end(ctx, stop) List[str]
            +format_response(ctx, content, stop) Dict
        }
@@ -866,7 +870,7 @@ classDiagram
        class AnthropicResponseBuilder {
            +prepare(request, engine) Tuple
            +format_stream_start(ctx) List[str]
-            +format_chunk(token) str
+            +format_chunk(token) List[str]
            +format_stream_end(ctx, stop) List[str]
            +format_response(ctx, content, stop) Dict
        }
@@ -1171,10 +1175,10 @@ classDiagram
 | **astrai.serialization** | Checkpoint | Model serialization |
 | **astrai.model** | AutoModel, AutoRegressiveLM, EmbeddingEncoder, DecoderBlock, GQA, MLA, MLP, DeepSeekMoE, AttnFactory, FFNFactory, RMSNorm, Linear, RotaryEmbedding, Embedding | Neural network model |
 | **astrai.tokenize** | AutoTokenizer, ChatTemplate | Tokenizer and chat template |
-| **astrai.trainer** | Trainer, TrainContext, TrainContextBuilder, BaseStrategy–GRPOStrategy, StrategyFactory, BaseScheduler–WSDScheduler, SchedulerFactory, TrainCallback(Protocol)–ValidationCallback, CallbackFactory, Muon | Training workflow |
+| **astrai.trainer** | Trainer, TrainContext, TrainContextBuilder, BaseStrategy–GRPOStrategy, StrategyFactory, BaseScheduler–WSDScheduler, SchedulerFactory, TrainCallback(Protocol)–ValidationCallback, CallbackFactory | Training workflow |
 | **astrai.inference** | InferenceEngine, InferenceScheduler, Executor, KVCache–KvcacheView, Allocator–Storage, Task, TaskManager, TaskStatus, GenerationRequest, GenerateResult, BaseSamplingStrategy–SamplingPipeline, ProtocolHandler, ResponseBuilder, OpenAIResponseBuilder, AnthropicResponseBuilder, StopChecker, GenContext, ChatMessage–MessagesRequest, app | Inference service |
 | **astrai.parallel** | spawn_parallel_fn, setup_parallel, get_rank/get_world_size/get_current_device, only_on_rank, BaseExecutor, ExecutorFactory, NoneExecutor, DDPExecutor, FSDPExecutor, GradientState, AccumOptimizer, AccumScheduler, ParallelModel, RowParallelLinear, ColumnParallelLinear | Distributed parallel & gradient accumulation |
-| **astrai.factory** | Registry, BaseFactory[T] | Component registration |
+| **astrai.factory** | BaseFactory | Component registration |
 | **astrai.protocols** | OptimizerProtocol, SchedulerProtocol | Structural subtyping for optimizer/scheduler wrappers |

 ## Design Patterns
@@ -46,10 +46,10 @@ The output `meta.json` records the storage format, key names, dtype, total token

 ### Format Detection

-`detect_format(load_path)` inspects the directory:
+`detect_format(load_path)` inspects the path:

- If `*.h5` files exist → `"h5"` (HDF5 backend)
- If `*.bin` + `meta.json` files exist → `"bin"` (memory-mapped backend)
+- If `load_path` is a file: checks suffix — `.h5`/`.hdf5` → `"h5"`, unknown suffix raises `ValueError`
+- If `load_path` is a directory: recursively globs for `*.h5`/`*.hdf5` files → `"h5"`, or `*.bin` + `**/meta.json` → `"bin"`

 ### Store Backends

@@ -83,7 +83,7 @@ DatasetFactory.load(train_type, load_path, window_size, stride=None, storage_typ
    → detect_format(load_path)
    → StoreFactory.create(storage_type)
    → Store.load(load_path)
-      → H5Store._normalize() / MmapStore._normalize()
+      → _normalize(raw)  # base Store, shared by both backends
        → Store._data[Dict[str, List[Tensor]]] + _cum[Dict[str, List[int]]]
          → BaseDataset.__getitem__(idx)
            → get_index(idx) → [begin, end)
@@ -23,7 +23,7 @@ RoPE is applied **before** KV cache write, not after — otherwise position enco

 ## KVCache System

-Six classes (plus two helpers) working together:
+Seven classes working together:

 ```
 KVCache (facade)
@@ -152,12 +152,13 @@ Supports `stop_sequences` and streaming via `event: content_block_delta`.
 data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":...,"model":"astrai",
       "choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

-data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,
+data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":0,"model":"astrai",
       "choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

-data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,
-       "choices":[{"index":0,"delta":{},"finish_reason":"stop"}],
-       "usage":{"prompt_tokens":5,"completion_tokens":1,"total_tokens":6}}
+data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":...,"model":"astrai",
+       "choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
+
+data: {"prompt_tokens":5,"completion_tokens":1,"total_tokens":6}

 data: [DONE]
 ```
@@ -167,7 +168,7 @@ data: [DONE]
 ```
 event: message_start
 data: {"type":"message_start","message":{"id":"msg_...","model":"astrai","role":"assistant",
-       "content":[],"stop_reason":null,...}}
+       "content":[],"usage":{"input_tokens":0}}}

 event: content_block_start
 data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
@@ -179,7 +180,7 @@ event: content_block_stop
 data: {"type":"content_block_stop","index":0}

 event: message_delta
-data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{...}}
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{...}}

 event: message_stop
 data: {"type":"message_stop"}
@@ -187,26 +188,20 @@ data: {"type":"message_stop"}

 ### Error Responses

-All endpoints use standard HTTP status codes:
+The server returns standard HTTP status codes. Pydantic validation errors (e.g. missing required fields)
+are handled automatically by FastAPI with 422 status. The only application-level error is engine initialization:

 | Status | Meaning |
 |--------|---------|
 | 200 | Success |
-| 400 | Invalid request (bad JSON, missing fields, validation error) |
-| 405 | Method not allowed |
 | 422 | Unprocessable entity (Pydantic validation) |
-| 500 | Internal server error (model crash, OOM, scheduler failure) |
 | 503 | Service unavailable (model not loaded, engine not ready) |

-Error response body:
+Error response body (503):

 ```json
 {
-    "error": {
-        "message": "Invalid request: max_tokens must be > 0",
-        "type": "invalid_request_error",
-        "code": 400
-    }
+    "detail": "Engine not initialized"
 }
 ```

@@ -220,16 +215,13 @@ Response:

 ```json
 {
-    "active_requests": 3,
-    "waiting_requests": 2,
-    "total_requests": 128,
-    "cache_usage": 0.45,
-    "tokens_generated": 10240
+    "total_tasks": 128,
+    "total_tokens": 10240,
+    "active_tasks": 3,
+    "waiting_queue": 2
 }
 ```

-`cache_usage` is the fraction of KV cache pages currently in use (0.0–1.0).
-
 ## Engine API

 ```python
@@ -53,7 +53,7 @@
 | `--ckpt_interval` | Iterations between checkpoints | 5000 |
 | `--ckpt_dir` | Checkpoint save directory | checkpoint |
 | `--start_epoch` | Resume from epoch (0 = from scratch) | 0 |
-| `--start_batch` | Resume from batch iteration | 0 |
+| `--start_samples` | Resume from sample count per rank | 0 |

 ### Validation

@@ -67,8 +67,8 @@
 | Parameter | Description | Default |
 |-----------|-------------|---------|
 | `--log_dir` | Directory for metric logs | checkpoint/logs |
-| `--log_interval` | Number of batch iterations between metric logs | 100 |
-| `--metrics` | Metrics to log (e.g. --metrics loss lr val_loss) | ["loss", "lr"] |
+| `--log_interval` | Number of optimizer steps between metric logs | 1 |
+| `--metrics` | Metrics to log (e.g. --metrics loss lr val_loss) | ["loss", "lr", "grad_norm"] |

 ### Gradient Checkpointing

@@ -100,6 +100,17 @@
 | `--grpo_sync_interval` | GRPO ref_model sync interval (steps) | 200 | `grpo` |
 | `--neftune_alpha` | NEFTune noise alpha (0=disabled, typical: 5.0) | 0.0 | `sft` |

+### Scheduler
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--schedule_type` | LR scheduler type (`cosine`, `sgdr`, `wsd`) | cosine |
+| `--min_rate` | Minimum LR as fraction of base LR | None (scheduler default) |
+| `--cycle_length` | SGDR first cycle length in steps | None (total_steps - warmup_steps) |
+| `--t_mult` | SGDR cycle length multiplier per restart | 2 |
+| `--stable_steps` | WSD stable plateau steps | None (required for wsd) |
+| `--decay_steps` | WSD decay steps | None (total_steps - warmup_steps - stable_steps) |
+
 ### Usage Example

 ```bash
@@ -178,7 +189,7 @@ python scripts/tools/generate.py \
 | `input_files` | path(s) | required | Input JSONL file(s), supports glob (`data/*.jsonl`) |
 | `--output_dir`, `-o` | path | required | Output directory for processed data |
 | `--config`, `-c` | path | required | Preprocessing pipeline config (JSON) |
-| `--num_workers` | int | `4` | Number of parallel workers |
+| `--tokenizer_path` | str | `params` | Path to tokenizer directory |

 Usage:
 ```bash
@@ -26,8 +26,9 @@ A single config file captures the entire pipeline, reusable and version-controll

 ```json
 {
+  "version":       1,
  "input":         {},   // sections (single) or sources (multi)
-  "mask":          {},   // role → "train" | "mask"
+  "mask":          {},   // role -> "train" | "mask"
  "mask_default":  "mask",
  "preprocessing": {},
  "output":        {}
@@ -220,11 +221,12 @@ Config:
 }
 ```

-Output keys: `prompts`, `responses`, `masks`, `rewards` (float32)
+Output keys: `prompts`, `prompts_mask`, `responses`, `masks`, `rewards` (float32)

 - `action: "value"` — extract raw values from JSONL without tokenisation
 - `list_field: true` — tokenise each list element independently, then concatenate
 - `mask_key: "masks"` — rename the auto-generated mask key (default: `responses_mask`)
+- `prompts_mask` is auto-generated (all masked) and unused by GRPOStrategy

 ---

@@ -266,7 +268,7 @@ When `sources` is set, `sections` is ignored.
 | `storage_format` | str | `"bin"` | `"bin"` (mmap) or `"h5"` |
 | `max_tokens_per_shard` | int | `100000000` | Flush threshold in cumulative tokens |
 | `dtype` | dict[str, str] | `{}` | Per-key tensor dtype override (e.g. `{"loss_mask": "bool"}`) |
-| `position_ids_mode` | str | `"none"` | How to compute position_ids: `"none"`, `"doc_reset"`, `"continuous"` |
+| `position_ids_mode` | str | `"doc_reset"` | How to compute position_ids: `"none"`, `"doc_reset"`, `"continuous"` |

 ---

@@ -274,12 +276,11 @@ When `sources` is set, `sections` is ignored.

 ### Template mode (`template: true`)

-For each message in the field's array:
-
 1. Prepend BOS token (masked)
-2. Render through `chat_template` for that single message
-3. Encode rendered text
-4. Apply mask rule for the message's role
+2. For each message in the field's array:
+   1. Render through `chat_template` for that single message
+   2. Encode rendered text
+   3. Apply mask rule for the message's role

 ### Non-template mode

@@ -287,7 +288,7 @@ Encode the field value as text. Mask value is 1 (train) or 0 (mask) per the sect

 ### Text config detection

-When no section uses `template` and all sections have `action: "train"`, the builder skips mask generation entirely — all tokens are trained.
+When no section uses `template` and all sections have `action: "train"`, the builder omits `loss_mask` from the output — all tokens are trained.

 ---

@@ -298,13 +299,15 @@ When no section uses `template` and all sections have `action: "train"`, the bui
 ```
 output/
  __default__/
-    meta.json
-    sequence.bin
-    loss_mask.bin
+    shard_0000/
+      meta.json
+      sequence.bin
+      loss_mask.bin
  wiki/
-    meta.json
-    sequence.bin
-    loss_mask.bin
+    shard_0000/
+      meta.json
+      sequence.bin
+      loss_mask.bin
 ```

 ### Multi-Shard (`bin`)
@@ -324,7 +327,7 @@ output/
      loss_mask.bin
 ```

-`MmapStore` discovers all shards under the domain directory via `rglob("meta.json")`.
+For `bin` format, `MmapStore` discovers all shards under the domain directory via `rglob("meta.json")`. For `h5` format, `H5Store` discovers `.h5`/`.hdf5` files via recursive glob.

 ---

@@ -349,7 +352,7 @@ python scripts/tools/preprocess.py data/grpo/*.jsonl -o output/grpo/ -c configs/
 from astrai.preprocessing.pipeline import Pipeline
 from astrai.config.preprocess_config import PipelineConfig

-config = PipelineConfig.from_json("sft.json")
+config = PipelineConfig.from_file("sft.json")
 Pipeline(
    config,
    ["data_part1.jsonl", "data_part2.jsonl"],
@@ -58,7 +58,9 @@ on_train_begin
        context.loss = loss.item()
        stand_loss = loss / executor.grad_accum_steps
        executor.backward(stand_loss)
-        context.iteration += 1
+        context.consumed_samples += (
+            context.config.batch_per_device * context.world_size
+        )
        on_batch_end

        if executor.sync_gradients:
@@ -78,13 +80,13 @@ on_train_end
 | `on_train_begin` | Before training starts | `GradientCheckpointingCallback` |
 | `on_epoch_begin` | Start of each epoch | `ProgressBarCallback` |
 | `on_batch_begin` | Every batch | — |
-| `on_optimizer_step` | Every accumulation window | `GradientClippingCallback`, `ValidationCallback` |
+| `on_optimizer_step` | Every accumulation window | `GradientClippingCallback`, `MetricLoggerCallback`, `ValidationCallback` |
 | `on_batch_end` | Every batch | `CheckpointCallback`, `MetricLoggerCallback`, `ProgressBarCallback` |
 | `on_epoch_end` | End of each epoch | `ProgressBarCallback` |
 | `on_error` | On exception during training | `CheckpointCallback`, `MetricLoggerCallback` |
 | `on_train_end` | Training ends (always via finally) | `CheckpointCallback`, `MetricLoggerCallback`, `GradientCheckpointingCallback` |

-Default callbacks (in order): `gradient_checkpointing` (activation checkpointing, optional), `checkpoint` (safetensors, rank-0), `metric_logger` (JSONL, rank-0), `progress_bar` (tqdm), `gradient_clipping`, `validation` (periodic validation on val_dataset).
+Default callbacks (in order): `gradient_checkpointing` (activation checkpointing, optional), `checkpoint` (safetensors, rank-0), `validation` (periodic validation on val_dataset), `metric_logger` (JSONL, rank-0), `progress_bar` (tqdm), `gradient_clipping`.

 ## Strategies

@@ -158,8 +160,8 @@ Callback wraps each `DecoderBlock.forward` with `torch.utils.checkpoint.checkpoi
 ## Checkpoint

 ```
-Checkpoint(state_dict, epoch, iteration, extra, meta, config)
-  ├── save(save_dir)    rank-0 only: meta.json (epoch/iteration/timestamp) + config.json (model config) + model.safetensors + optional {key}.pt (optimizer.pt, scheduler.pt)
+Checkpoint(state_dict, epoch, consumed_samples, extra, meta, config)
+  ├── save(save_dir)    rank-0 only: meta.json (epoch/consumed_samples/timestamp) + config.json (model config) + model.safetensors + optional {key}.pt (optimizer.pt, scheduler.pt)
  └── load(save_dir, broadcast=False)    loads from local disk; set broadcast=True to broadcast metadata from rank-0
 ```

@@ -1,4 +1,4 @@
-__version__ = "1.3.7"
+__version__ = "1.3.8"
 __author__ = "ViperEkura"

 from astrai.config import (
@@ -47,7 +47,6 @@ from astrai.trainer import (
    BaseScheduler,
    BaseStrategy,
    CallbackFactory,
-    Muon,
    SchedulerFactory,
    StrategyFactory,
    TrainCallback,
@@ -75,7 +74,6 @@ __all__ = [
    "GenerationRequest",
    "InferenceEngine",
    "LoRAConfig",
-    "Muon",
    "Pipeline",
    "PipelineConfig",
    "ProtocolHandler",
@@ -96,7 +96,7 @@ class OutputConfig(BaseConfig):
    storage_format: str = "bin"
    max_tokens_per_shard: int = 100_000_000
    dtype: Dict[str, str] = field(default_factory=dict)
-    position_ids_mode: str = "none"
+    position_ids_mode: str = "doc_reset"


@dataclass
@@ -47,14 +47,18 @@ class TrainConfig(BaseConfig):

    # checkpoint setting
    start_epoch: int = field(default=0, metadata={"help": "Start epoch for training."})
-    start_batch: int = field(
-        default=0, metadata={"help": "Start batch iteration for training."}
+    start_samples: int = field(
+        default=0,
+        metadata={
+            "help": "Start samples count (per rank). Superseded by checkpoint consumed_samples."
+        },
    )
    ckpt_dir: str = field(
        default="./checkpoint", metadata={"help": "Checkpoint directory."}
    )
    ckpt_interval: int = field(
-        default=5000, metadata={"help": "Number of iterations between checkpoints."}
+        default=5000,
+        metadata={"help": "Number of optimizer steps between checkpoints."},
    )

    # lora setting
@@ -67,12 +71,8 @@ class TrainConfig(BaseConfig):
    log_dir: str = field(
        default="./checkpoint/logs", metadata={"help": "Directory for metric logs."}
    )
-    log_interval: int = field(
-        default=100,
-        metadata={"help": "Number of batch iterations between metric logs."},
-    )
    metrics: List[str] = field(
-        default_factory=lambda: ["loss", "lr"],
+        default_factory=lambda: ["loss", "lr", "grad_norm"],
        metadata={"help": "Metrics to record during training."},
    )

@@ -5,10 +5,13 @@ from astrai.dataset.dataset import (
 from astrai.dataset.sampler import ResumableDistributedSampler
 from astrai.dataset.storage import (
    H5Store,
+    JsonlStore,
    MmapStore,
    Store,
    StoreFactory,
    detect_format,
+)
+from astrai.serialization import (
    load_bin,
    load_h5,
    save_bin,
@@ -22,6 +25,7 @@ __all__ = [
    "StoreFactory",
    "H5Store",
    "MmapStore",
+    "JsonlStore",
    "detect_format",
    "save_h5",
    "load_h5",
@@ -48,24 +48,26 @@ class BaseDataset(Dataset, ABC):
                f"Missing: {missing}"
            )

-    def load(self, load_path: str, storage_type: Optional[str] = None):
+    def load(self, load_path: str, storage_type: Optional[str] = None, **kwargs):
        """Load dataset from the given path.

        Auto-detects the storage format if not specified.

        Args:
            load_path: Path to the data directory or file
-            storage_type: Force a specific storage type ("h5", "bin"),
+            storage_type: Force a specific storage type ("h5", "bin", "jsonl"),
                          or None for auto-detection
+            **kwargs: Extra arguments forwarded to the store constructor and
+                      to ``store.load()``.

        Raises:
            KeyError: If the loaded storage is missing required keys.
        """
        if storage_type is None:
            storage_type = detect_format(load_path)
-        self.storage = StoreFactory.create(storage_type)
+        self.storage = StoreFactory.create(storage_type, **kwargs)
        self._load_path = load_path
-        self.storage.load(load_path)
+        self.storage.load(load_path, **kwargs)
        self._validate_keys()

    @property
@@ -144,6 +146,7 @@ class DatasetFactory(BaseFactory["BaseDataset"]):
        window_size: int,
        stride: Optional[int] = None,
        storage_type: Optional[str] = None,
+        **kwargs,
    ) -> "BaseDataset":
        """Create and load a dataset in one step.

@@ -152,7 +155,8 @@ class DatasetFactory(BaseFactory["BaseDataset"]):
            load_path: Path to the data file
            window_size: Window size for data sampling
            stride: Stride between consecutive samples (default: same as window_size)
-            storage_type: Storage type ("h5", "bin") or None for auto-detection
+            storage_type: Storage type ("h5", "bin", "jsonl") or None for auto-detection
+            **kwargs: Extra arguments forwarded to ``dataset.load()``.

        Returns:
            Loaded dataset instance
@@ -161,7 +165,7 @@ class DatasetFactory(BaseFactory["BaseDataset"]):
            stride = window_size

        dataset = cls.create(train_type, window_size, stride)
-        dataset.load(load_path, storage_type=storage_type)
+        dataset.load(load_path, storage_type=storage_type, **kwargs)

        return dataset

@@ -74,6 +74,7 @@ class ResumableDistributedSampler(Sampler[int]):

        self.epoch += 1
        self._indices = None
+        self.iter = self.iter % self.num_samples_per_replica

    @property
    def _remaining(self):
@@ -14,85 +14,31 @@ Key properties:
  - Explicit length: _length = min(total elements across keys), set at load,
                      __len__ returns O(1)
  - Zero-copy mmap:  MmapStore wraps np.memmap(mode="r"), all DataLoader
-                      workers share OS page-cache pages
+                       workers share OS page-cache pages
 """

 import bisect
 import glob
 import json
-import os
+import logging
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Dict, List, Union

-import h5py
-import numpy as np
 import torch
 from torch import Tensor

+from astrai.config.preprocess_config import PipelineConfig
 from astrai.factory import BaseFactory
+from astrai.preprocessing.builder import MaskBuilderFactory
+from astrai.preprocessing.position_id import PositionIdStrategyFactory
+from astrai.serialization import (
+    load_bin,
+    load_h5,
+)
+from astrai.tokenize import AutoTokenizer

-
-def save_h5(file_path: str, file_name: str, tensor_group: Dict[str, List[Tensor]]):
-    os.makedirs(file_path, exist_ok=True)
-    full_file_path = os.path.join(file_path, f"{file_name}.h5")
-    with h5py.File(full_file_path, "w") as f:
-        for key, tensors in tensor_group.items():
-            grp = f.create_group(key)
-            for idx, tensor in enumerate(tensors):
-                arr = tensor.cpu().numpy()
-                grp.create_dataset(f"data_{idx}", data=arr)
-
-
-def load_h5(file_path: str, share_memory=True) -> Dict[str, List[Tensor]]:
-    tensor_group: Dict[str, List[Tensor]] = {}
-
-    root_path = Path(file_path)
-    h5_files = list(root_path.rglob("*.h5")) + list(root_path.rglob("*.hdf5"))
-
-    for h5_file in h5_files:
-        with h5py.File(h5_file, "r") as f:
-            for key in f.keys():
-                grp = f[key]
-                dsets = []
-                for dset_name in grp.keys():
-                    dset = grp[dset_name]
-                    tensor = torch.from_numpy(dset[:])
-                    if share_memory:
-                        tensor = tensor.share_memory_()
-                    dsets.append(tensor)
-
-                if tensor_group.get(key) is None:
-                    tensor_group[key] = []
-                tensor_group[key].extend(dsets)
-
-    return tensor_group
-
-
-def save_bin(file_path: str, tensor_group: Dict[str, List[Tensor]]):
-    os.makedirs(file_path, exist_ok=True)
-    meta = {}
-    for key, tensors in tensor_group.items():
-        cat = torch.cat(tensors, dim=0)
-        meta[key] = {"shape": list(cat.shape), "dtype": str(cat.dtype).split(".")[-1]}
-        np.asarray(cat.cpu().numpy()).tofile(os.path.join(file_path, f"{key}.bin"))
-    with open(os.path.join(file_path, "meta.json"), "w") as f:
-        json.dump(meta, f)
-
-
-def load_bin(file_path: str) -> Dict[str, List[Tensor]]:
-    with open(os.path.join(file_path, "meta.json"), "r") as f:
-        meta = json.load(f)
-    segments: Dict[str, List[Tensor]] = {}
-    for key, info in meta.items():
-        arr = np.memmap(
-            os.path.join(file_path, f"{key}.bin"),
-            dtype=info["dtype"],
-            mode="r+",
-            shape=tuple(info["shape"]),
-        )
-        segments[key] = [torch.from_numpy(arr)]
-    return segments
+logger = logging.getLogger(__name__)


 def detect_format(load_path: str) -> str:
@@ -102,7 +48,7 @@ def detect_format(load_path: str) -> str:
        load_path: Directory or file path

    Returns:
-        Format string ("h5" or "bin")
+        Format string ("h5", "bin", or "jsonl")

    Raises:
        FileNotFoundError: If no supported data files are found
@@ -112,6 +58,8 @@ def detect_format(load_path: str) -> str:
        suffix = root.suffix.lower()
        if suffix in (".h5", ".hdf5"):
            return "h5"
+        if suffix == ".jsonl":
+            return "jsonl"
        raise ValueError(f"Unsupported file format: {suffix}")

    h5_files = [
@@ -128,6 +76,11 @@ def detect_format(load_path: str) -> str:
        ) > 0
        if has_meta:
            return "bin"
+    jsonl_files = [
+        Path(p) for p in glob.glob(str(root / "**" / "*.jsonl"), recursive=True)
+    ]
+    if jsonl_files:
+        return "jsonl"
    raise FileNotFoundError(f"No supported data files found at {load_path}")


@@ -264,3 +217,96 @@ class MmapStore(Store):
        self._normalize(all_raw)
        for tensors in self._data.values():
            self._mmap_refs.extend(tensors)
+
+
+@StoreFactory.register("jsonl")
+class JsonlStore(Store):
+    """On-the-fly tokenization store for raw JSONL files.
+
+    A JSONL dataset directory contains ``*.jsonl`` files plus a
+    ``dataset_config.json`` file that follows the same schema as
+    :class:`PipelineConfig` with an additional ``tokenizer_path`` field.
+    Records are tokenized when the store is loaded and concatenated into
+    segmented tensors matching the key layout expected by the dataset
+    classes (``sequence``, ``loss_mask``, ``position_ids``, ...).
+    """
+
+    CONFIG_NAME = "dataset_config.json"
+
+    def load(self, path: str):
+        root = Path(path)
+        config_path = root / self.CONFIG_NAME
+        if not config_path.exists():
+            raise FileNotFoundError(
+                f"JSONL dataset config not found: {config_path}. "
+                f"Expected {self.CONFIG_NAME} alongside *.jsonl files."
+            )
+
+        with open(config_path, "r", encoding="utf-8") as f:
+            raw_config = json.load(f)
+
+        tokenizer_path = raw_config.pop("tokenizer_path", None)
+        if tokenizer_path is None:
+            raise ValueError(
+                f"JSONL dataset config must specify 'tokenizer_path': {config_path}"
+            )
+
+        self.config = PipelineConfig.from_dict(raw_config)
+        tokenizer = AutoTokenizer.from_pretrained(tokenizer_path)
+        mask_builder = MaskBuilderFactory.create("sectioned")
+        position_strategy = PositionIdStrategyFactory.create(
+            self.config.output.position_ids_mode
+        )
+
+        raw: Dict[str, List[Tensor]] = {}
+        doc_sequences: List[List[int]] = []
+
+        for jsonl_path in sorted(root.glob("*.jsonl")):
+            with open(jsonl_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        item = json.loads(line)
+                    except json.JSONDecodeError:
+                        logger.warning(
+                            "Failed to parse JSON line in %s, skipping", jsonl_path
+                        )
+                        continue
+
+                    result = mask_builder.build(item, self.config, tokenizer)
+                    if result is None:
+                        continue
+
+                    result.pop("domain", None)
+                    primary_ids = self._primary_ids(result)
+                    if not primary_ids:
+                        continue
+
+                    doc_sequences.append(primary_ids)
+                    for key, ids in result.items():
+                        if key not in raw:
+                            raw[key] = []
+                        raw[key].append(torch.tensor(ids, dtype=self._infer_dtype(ids)))
+
+        pos_ids = position_strategy.generate(doc_sequences)
+        if pos_ids:
+            raw["position_ids"] = [torch.tensor(pos_ids, dtype=torch.int32)]
+
+        self._normalize(raw)
+
+    @staticmethod
+    def _primary_ids(result: dict) -> List[int]:
+        """Return the first integer list in *result* as the primary id sequence."""
+        for val in result.values():
+            if isinstance(val, list) and val and isinstance(val[0], int):
+                return val
+        return []
+
+    @staticmethod
+    def _infer_dtype(ids: List) -> torch.dtype:
+        """Infer tensor dtype from the first element of a token/value list."""
+        if ids and isinstance(ids[0], float):
+            return torch.float32
+        return torch.int32
@@ -37,7 +37,7 @@ def _resolve_type(
    ns = vars(mod)

    if isinstance(arg, ForwardRef):
-        return arg._evaluate(ns, None, frozenset(), recursive_guard=frozenset())
+        return arg._evaluate(ns, None, recursive_guard=frozenset())

    return ns.get(name)

@@ -30,10 +30,14 @@ from astrai.inference.api.openai import OpenAIResponseBuilder
 from astrai.inference.core import (
    STOP,
    Allocator,
+    CacheView,
+    ContiguousCache,
+    ContiguousCacheView,
    Executor,
    InferenceScheduler,
    KVCache,
-    KvcacheView,
+    PageCache,
+    PageCacheView,
    PagePool,
    PrefixCache,
    Storage,
@@ -63,8 +67,12 @@ __all__ = [
    "TaskManager",
    "TaskStatus",
    "Allocator",
+    "CacheView",
    "KVCache",
-    "KvcacheView",
+    "ContiguousCache",
+    "ContiguousCacheView",
+    "PageCache",
+    "PageCacheView",
    "PagePool",
    "PrefixCache",
    "Storage",
@@ -2,8 +2,12 @@

 from astrai.inference.core.cache import (
    Allocator,
+    CacheView,
+    ContiguousCache,
+    ContiguousCacheView,
    KVCache,
-    KvcacheView,
+    PageCache,
+    PageCacheView,
    PagePool,
    PrefixCache,
    Storage,
@@ -16,8 +20,12 @@ from astrai.inference.core.task import STOP, Task, TaskManager, TaskStatus

 __all__ = [
    "Allocator",
+    "CacheView",
    "KVCache",
-    "KvcacheView",
+    "ContiguousCache",
+    "ContiguousCacheView",
+    "PageCache",
+    "PageCacheView",
    "PagePool",
    "PrefixCache",
    "Storage",
@@ -1,4 +1,5 @@
 import threading
+from abc import ABC, abstractmethod
 from collections import OrderedDict
 from typing import Callable, Dict, List, Optional, Tuple

@@ -62,7 +63,8 @@ class Allocator:

    def touch(self, idx: int):
        with self._lock:
-            self._lru.move_to_end(idx)
+            if idx in self._lru:
+                self._lru.move_to_end(idx)


 class PrefixCache:
@@ -274,7 +276,42 @@ class Storage:
        return k, v


-class KvcacheView:
+class CacheView(ABC):
+    """Abstract view passed to attention layers for KV-cache I/O."""
+
+    @abstractmethod
+    def write(self, layer_id: int, k: Tensor, v: Tensor): ...
+
+    @abstractmethod
+    def gather(self, layer_id: int) -> Tuple[Tensor, Tensor]: ...
+
+
+class KVCache(ABC):
+    """Abstract KV-cache facade for scheduler/executor."""
+
+    @abstractmethod
+    def task_alloc(self, task_id: str, prompt_ids: List[int]) -> bool: ...
+
+    @abstractmethod
+    def task_free(self, task_id: str): ...
+
+    @abstractmethod
+    def task_extend(self, task_id: str, pos: int) -> bool: ...
+
+    @abstractmethod
+    def bind_tasks(
+        self, task_ids: List[str], total_len: int, device: torch.device
+    ) -> CacheView: ...
+
+    def task_cached(self, task_id: str) -> int:
+        return 0
+
+    def task_record_hashes(
+        self, task_id: str, prompt_ids: List[int], start_logical_page: int = 0
+    ): ...
+
+
+class PageCacheView(CacheView):
    """Bundles Storage + page_table + total_len for attention layers."""

    def __init__(self, storage: Storage, page_table: Tensor, total_len: int = 0):
@@ -290,8 +327,8 @@ class KvcacheView:
        return self._storage.gather(layer_id, self._page_table, self._total_len)


-class KVCache:
-    """Facade: page management + KV-cache I/O for continuous batching."""
+class PageCache(KVCache):
+    """Paged KV-cache with prefix sharing."""

    def __init__(
        self,
@@ -361,8 +398,102 @@ class KVCache:
        for i in range(start_logical_page, full_pages):
            self._pool.record(page_table[i], prompt_ids, i)

-    def make_table_tensor(self, task_ids: List[str], device: torch.device) -> Tensor:
-        return self._table.table_tensor(task_ids, device)
+    def bind_tasks(
+        self, task_ids: List[str], total_len: int, device: torch.device
+    ) -> PageCacheView:
+        page_table = self._table.table_tensor(task_ids, device)
+        return PageCacheView(self._storage, page_table, total_len)

-    def bind(self, page_table: Tensor, total_len: int = 0) -> KvcacheView:
-        return KvcacheView(self._storage, page_table, total_len)
+
+class ContiguousCacheView(CacheView):
+    """Contiguous KV-cache view for attention layers."""
+
+    def __init__(
+        self, cache: "ContiguousCache", batch_indices: Tensor, total_len: int = 0
+    ):
+        self._cache = cache
+        self._batch_indices = batch_indices
+        self._total_len = total_len
+
+    def write(self, layer_id: int, k: Tensor, v: Tensor):
+        seq_len = k.size(1)
+        start_pos = self._total_len - seq_len
+        indices = self._batch_indices
+        self._cache.k[layer_id, indices, start_pos : start_pos + seq_len] = k
+        self._cache.v[layer_id, indices, start_pos : start_pos + seq_len] = v
+        new_len = start_pos + seq_len
+        for s in indices.tolist():
+            cur = self._cache._slot_len.get(s, 0)
+            if new_len > cur:
+                self._cache._slot_len[s] = new_len
+
+    def gather(self, layer_id: int) -> Tuple[Tensor, Tensor]:
+        max_len = max(
+            self._cache._slot_len.get(int(s), 0) for s in self._batch_indices.tolist()
+        )
+        indices = self._batch_indices
+        k = self._cache.k[layer_id, indices, :max_len]
+        v = self._cache.v[layer_id, indices, :max_len]
+        return k, v
+
+
+class ContiguousCache(KVCache):
+    """Contiguous per-slot KV cache (default implementation)."""
+
+    def __init__(
+        self,
+        n_layers: int,
+        max_batch_size: int,
+        max_seq_len: int,
+        n_kv_heads: int,
+        head_dim: int,
+        device: torch.device,
+        dtype: torch.dtype,
+    ):
+        self.max_seq_len = max_seq_len
+        self.k = torch.zeros(
+            n_layers,
+            max_batch_size,
+            max_seq_len,
+            n_kv_heads,
+            head_dim,
+            device=device,
+            dtype=dtype,
+        )
+        self.v = torch.zeros(
+            n_layers,
+            max_batch_size,
+            max_seq_len,
+            n_kv_heads,
+            head_dim,
+            device=device,
+            dtype=dtype,
+        )
+        self._slot_len: Dict[int, int] = {}
+        self._task_slot: Dict[str, int] = {}
+        self._free_slots = list(range(max_batch_size))
+        self._device = device
+
+    def task_alloc(self, task_id: str, prompt_ids: List[int]) -> bool:
+        if not self._free_slots:
+            return False
+        slot = self._free_slots.pop(0)
+        self._task_slot[task_id] = slot
+        self._slot_len[slot] = 0
+        return True
+
+    def task_free(self, task_id: str):
+        slot = self._task_slot.pop(task_id, None)
+        if slot is not None:
+            self._slot_len.pop(slot, None)
+            self._free_slots.append(slot)
+
+    def task_extend(self, task_id: str, pos: int) -> bool:
+        return pos < self.max_seq_len
+
+    def bind_tasks(
+        self, task_ids: List[str], total_len: int, device: torch.device
+    ) -> ContiguousCacheView:
+        slots = [self._task_slot[tid] for tid in task_ids]
+        batch_indices = torch.tensor(slots, dtype=torch.long, device=device)
+        return ContiguousCacheView(self, batch_indices, total_len)
@@ -19,13 +19,13 @@ class Executor:
        self,
        model: AutoModel,
        tokenizer: AutoTokenizer,
-        page_cache: KVCache,
+        kv_cache: KVCache,
        device: Optional[str] = None,
        dtype: Optional[torch.dtype] = None,
    ):
        self.model = model
        self.tokenizer = tokenizer
-        self.page_cache = page_cache
+        self.kv_cache = kv_cache
        self.device = device or next(model.parameters()).device
        self.dtype = dtype or next(model.parameters()).dtype

@@ -43,7 +43,6 @@ class Executor:
        )

        task_ids = [t.task_id for t in tasks]
-        page_tables = self.page_cache.make_table_tensor(task_ids, self.device)

        with torch.inference_mode():
            self.model(
@@ -53,7 +52,7 @@ class Executor:
                )
                .unsqueeze(0)
                .expand(batch_sz, -1),
-                paged_cache=self.page_cache.bind(page_tables, total_len=prompt_len),
+                paged_cache=self.kv_cache.bind_tasks(task_ids, prompt_len, self.device),
            )

    def execute_decode(self, tasks: List[Task]) -> List[int]:
@@ -72,7 +71,6 @@ class Executor:
        total_len = position_ids.max().item() + 1

        task_ids = [t.task_id for t in tasks]
-        page_tables = self.page_cache.make_table_tensor(task_ids, self.device)

        temperatures = torch.tensor([t.temperature for t in tasks], device=self.device)
        top_ks = torch.tensor([t.top_k for t in tasks], device=self.device)
@@ -81,7 +79,7 @@ class Executor:
        with torch.inference_mode():
            outputs = self.model(
                input_ids.unsqueeze(1),
-                paged_cache=self.page_cache.bind(page_tables, total_len=total_len),
+                paged_cache=self.kv_cache.bind_tasks(task_ids, total_len, self.device),
                position_ids=position_ids.unsqueeze(1),
            )
            logits = outputs["logits"][:, -1, :]
@@ -4,7 +4,7 @@ from typing import Any, Dict, List, Optional, Tuple

 import torch

-from astrai.inference.core.cache import KVCache
+from astrai.inference.core.cache import ContiguousCache, KVCache
 from astrai.inference.core.executor import Executor
 from astrai.inference.core.task import STOP, Task, TaskManager, TaskStatus
 from astrai.model.automodel import AutoModel
@@ -14,7 +14,7 @@ logger = logging.getLogger(__name__)


 class InferenceScheduler:
-    """Four-phase continuous batching loop: cleanup -> refill -> prefill -> decode."""
+    """Continuous batching loop: cleanup -> refill -> prefill -> decode (all groups)."""

    def __init__(
        self,
@@ -23,9 +23,9 @@ class InferenceScheduler:
        max_batch_size: int = 16,
        max_seq_len: Optional[int] = None,
        max_prompt_len: int = 2048,
-        page_size: int = 64,
        device: Optional[str] = None,
        dtype: Optional[torch.dtype] = None,
+        cache: Optional[KVCache] = None,
    ):
        config = model.config

@@ -41,19 +41,20 @@ class InferenceScheduler:
        self.device = device or next(model.parameters()).device
        self.dtype = dtype or next(model.parameters()).dtype

-        n_pages = (
-            max_batch_size * (self.max_seq_len + page_size) + page_size - 1
-        ) // page_size
+        head_dim = config.dim // config.n_heads

-        self._page_cache = KVCache(
-            config.n_layers,
-            n_pages,
-            page_size,
-            config.n_kv_heads,
-            config.dim // config.n_heads,
-            self.device,
-            self.dtype,
-        )
+        if cache is not None:
+            self._cache = cache
+        else:
+            self._cache = ContiguousCache(
+                config.n_layers,
+                max_batch_size,
+                self.max_seq_len,
+                config.n_kv_heads,
+                head_dim,
+                self.device,
+                self.dtype,
+            )

        self._task_mgr = TaskManager(
            tokenizer=tokenizer,
@@ -65,7 +66,7 @@ class InferenceScheduler:
        self._executor = Executor(
            model=model,
            tokenizer=tokenizer,
-            page_cache=self._page_cache,
+            kv_cache=self._cache,
            device=self.device,
            dtype=self.dtype,
        )
@@ -78,18 +79,19 @@ class InferenceScheduler:

    def remove_task(self, task_id: str):
        for task in self._task_mgr.remove_task(task_id):
-            self._page_cache.task_free(task.task_id)
+            self._cache.task_free(task.task_id)

    def get_stats(self) -> Dict[str, Any]:
        return self._task_mgr.get_stats()

    def _run_generation_loop(self):
        stop_ids = self._task_mgr.tokenizer.stop_ids
+        cache = self._cache
        try:
            while not self._stop_event.is_set():
                finished = self._task_mgr.remove_finished_tasks(stop_ids)
                for task in finished:
-                    self._page_cache.task_free(task.task_id)
+                    cache.task_free(task.task_id)

                active = self._task_mgr.get_active_tasks()
                available = self._task_mgr.max_batch_size - len(active)
@@ -97,7 +99,7 @@ class InferenceScheduler:
                    candidates = self._task_mgr.pull_candidates(available)
                    failed = []
                    for task in candidates:
-                        if self._page_cache.task_alloc(task.task_id, task.prompt_ids):
+                        if cache.task_alloc(task.task_id, task.prompt_ids):
                            self._task_mgr.activate(task)
                        else:
                            failed.append(task)
@@ -112,7 +114,7 @@ class InferenceScheduler:
                    t
                    for t in self._task_mgr.get_active_tasks()
                    if t.output_tokens == 0
-                    and self._page_cache.task_cached(t.task_id) < len(t.prompt_ids)
+                    and cache.task_cached(t.task_id) < len(t.prompt_ids)
                ]
                if to_prefill:
                    for t in to_prefill:
@@ -122,36 +124,34 @@ class InferenceScheduler:
                    for t in to_prefill:
                        key = (
                            len(t.prompt_ids),
-                            self._page_cache.task_cached(t.task_id),
+                            cache.task_cached(t.task_id),
                        )
                        groups.setdefault(key, []).append(t)

                    for (prompt_len, start_pos), group in groups.items():
                        self._executor.execute_prefill(group, prompt_len, start_pos)
-                        start_logical_page = start_pos // self._page_cache.page_size
+                        start_logical_page = start_pos // getattr(
+                            cache, "page_size", 64
+                        )
                        for t in group:
-                            self._page_cache.task_record_hashes(
-                                t.task_id,
-                                t.prompt_ids,
-                                start_logical_page=start_logical_page,
+                            cache.task_record_hashes(
+                                t.task_id, t.prompt_ids, start_logical_page
                            )

                pos_groups: Dict[int, List[Task]] = {}
                for t in self._task_mgr.get_active_tasks():
                    pos_groups.setdefault(t.next_pos, []).append(t)

-                if pos_groups:
-                    best_key = max(pos_groups, key=lambda k: len(pos_groups[k]))
-                    group = sorted(pos_groups[best_key], key=lambda t: t.task_id)
+                for next_pos in sorted(pos_groups.keys()):
+                    group = sorted(pos_groups[next_pos], key=lambda t: t.task_id)

                    valid: List[Task] = []
                    for t in group:
-                        if self._page_cache.task_extend(t.task_id, t.next_pos):
+                        if cache.task_extend(t.task_id, t.next_pos):
                            valid.append(t)
                        else:
                            t.status = TaskStatus.ABORTED
-                            if t.stream_callback:
-                                t.stream_callback(STOP)
+                            self._task_mgr.invoke_callback(t.task_id, STOP)

                    if valid:
                        next_tokens = self._executor.execute_decode(valid)
@@ -159,32 +159,23 @@ class InferenceScheduler:
                        for t, ntok in zip(valid, next_tokens):
                            t.output_ids.append(ntok)
                            t.output_tokens += 1
-                            pos = t.input_tokens + t.output_tokens
-                            extend_ok = self._page_cache.task_extend(t.task_id, pos)
-                            if t.stream_callback:
-                                t.stream_callback(
-                                    self._task_mgr.tokenizer.decode([ntok])
-                                )
-                            if not extend_ok:
-                                t.status = TaskStatus.ABORTED
-                                if t.stream_callback:
-                                    t.stream_callback(STOP)
+                            self._task_mgr.invoke_callback(
+                                t.task_id,
+                                self._task_mgr.tokenizer.decode([ntok]),
+                            )

                        for t in valid:
                            if t.is_finished(stop_ids):
-                                if t.stream_callback:
-                                    t.stream_callback(STOP)
+                                self._task_mgr.invoke_callback(t.task_id, STOP)

        except Exception as e:
            self._stop_event.set()
            logger.error(f"Scheduler loop crashed: {e}", exc_info=True)
            for task in self._task_mgr.get_active_tasks():
-                if task.stream_callback:
-                    task.stream_callback(STOP)
-                self._page_cache.task_free(task.task_id)
+                self._task_mgr.invoke_callback(task.task_id, STOP)
+                cache.task_free(task.task_id)
            for task in self._task_mgr.get_waiting_tasks():
-                if task.stream_callback:
-                    task.stream_callback(STOP)
+                self._task_mgr.invoke_callback(task.task_id, STOP)
            self._task_mgr.clear_queues()

    def start(self):
@@ -202,12 +193,10 @@ class InferenceScheduler:
            self._loop_thread.join(timeout=2.0)
        self._loop_thread = None
        for task in self._task_mgr.get_active_tasks():
-            if task.stream_callback:
-                task.stream_callback(STOP)
-            self._page_cache.task_free(task.task_id)
+            self._task_mgr.invoke_callback(task.task_id, STOP)
+            self._cache.task_free(task.task_id)
        for task in self._task_mgr.get_waiting_tasks():
-            if task.stream_callback:
-                task.stream_callback(STOP)
+            self._task_mgr.invoke_callback(task.task_id, STOP)
        self._task_mgr.clear_queues()
        if torch.cuda.is_available():
            torch.cuda.empty_cache()
@@ -33,7 +33,6 @@ class Task:
        temperature: float = 1.0,
        top_p: float = 1.0,
        top_k: int = 50,
-        stream_callback: Optional[Callable[[str], None]] = None,
    ):
        self.task_id = task_id
        self.prompt_ids = prompt_ids
@@ -48,7 +47,6 @@ class Task:
        self.output_tokens: int = 0
        self.arrival_time = time.time()
        self.finish_time: Optional[float] = None
-        self.stream_callback = stream_callback

    @property
    def next_pos(self) -> int:
@@ -79,6 +77,7 @@ class TaskManager:

        self.waiting_queue: Deque[Task] = deque()
        self.active_tasks: List[Task] = []
+        self._callbacks: Dict[str, Callable[[str], None]] = {}

        self._task_event = threading.Event()
        self._lock = threading.Lock()
@@ -117,12 +116,13 @@ class TaskManager:
            temperature=temperature,
            top_p=top_p,
            top_k=top_k,
-            stream_callback=stream_callback,
        )

        with self._lock:
            self.waiting_queue.append(task)
            self._total_tasks += 1
+            if stream_callback:
+                self._callbacks[task_id] = stream_callback

        self._task_event.set()
        return task_id
@@ -134,8 +134,14 @@ class TaskManager:
                t for t in self.waiting_queue if t.task_id != task_id
            )
            self.active_tasks = [t for t in self.active_tasks if t.task_id != task_id]
+            self._callbacks.pop(task_id, None)
        return removed_active

+    def invoke_callback(self, task_id: str, token: str):
+        cb = self._callbacks.get(task_id)
+        if cb:
+            cb(token)
+
    def get_stats(self) -> Dict[str, Any]:
        return {
            "total_tasks": self._total_tasks,
@@ -204,6 +210,7 @@ class TaskManager:
        with self._lock:
            self.waiting_queue.clear()
            self.active_tasks.clear()
+            self._callbacks.clear()

    def wake(self):
        self._task_event.set()
@@ -8,6 +8,7 @@ from typing import Any, AsyncGenerator, Dict, Generator, List, Optional, Tuple,
 import torch
 import torch.nn as nn

+from astrai.inference.core.cache import KVCache
 from astrai.inference.core.scheduler import InferenceScheduler
 from astrai.inference.core.task import STOP
 from astrai.tokenize import AutoTokenizer
@@ -101,6 +102,7 @@ class InferenceEngine:
        max_seq_len: Optional[int] = None,
        max_prompt_len: int = 2048,
        page_size: int = 128,
+        cache: Optional[KVCache] = None,
    ):
        self.model = model
        self.tokenizer = tokenizer
@@ -110,7 +112,7 @@ class InferenceEngine:
            max_batch_size=max_batch_size,
            max_seq_len=max_seq_len,
            max_prompt_len=max_prompt_len,
-            page_size=page_size,
+            cache=cache,
        )

        self.scheduler.start()
@@ -6,7 +6,7 @@ import torch.nn.functional as F
 from torch import Tensor

 from astrai.factory import BaseFactory
-from astrai.inference.core.cache import KvcacheView
+from astrai.inference.core.cache import CacheView
 from astrai.model.components.linear import Linear
 from astrai.model.components.norm import RMSNorm
 from astrai.model.components.rope import apply_rotary_emb
@@ -75,7 +75,7 @@ class GQA(nn.Module):
        x: Tensor,
        rotary_emb: Tensor,
        attn_mask: Tensor = None,
-        paged_cache: Optional[KvcacheView] = None,
+        paged_cache: Optional[CacheView] = None,
    ) -> Tensor:
        is_causal = attn_mask is None

@@ -162,7 +162,7 @@ class MLA(nn.Module):
        x: Tensor,
        rotary_emb: Tensor,
        attn_mask: Tensor = None,
-        paged_cache: Optional[KvcacheView] = None,
+        paged_cache: Optional[CacheView] = None,
    ) -> Tensor:
        bsz, seq_len, _ = x.size()
        is_causal = attn_mask is None
@@ -4,7 +4,7 @@ from typing import Optional
 import torch.nn as nn
 from torch import Tensor

-from astrai.inference.core.cache import KvcacheView
+from astrai.inference.core.cache import CacheView
 from astrai.model.components.attention import AttnFactory
 from astrai.model.components.mlp import FFNFactory
 from astrai.model.components.norm import RMSNorm
@@ -25,7 +25,7 @@ class DecoderBlock(nn.Module):
        x: Tensor,
        rotary_emb: Tensor,
        attention_mask: Optional[Tensor] = None,
-        paged_cache: Optional[KvcacheView] = None,
+        paged_cache: Optional[CacheView] = None,
    ) -> Tensor:
        attn_output = self.attention(
            self.input_norm(x),
@@ -5,7 +5,7 @@ import torch.nn as nn
 from torch import Tensor

 from astrai.config.model_config import AutoRegressiveLMConfig
-from astrai.inference.core.cache import KvcacheView
+from astrai.inference.core.cache import CacheView
 from astrai.model.automodel import AutoModel
 from astrai.model.components.decoder_block import DecoderBlock
 from astrai.model.components.embedding import Embedding
@@ -112,7 +112,7 @@ class AutoRegressiveLM(AutoModel):
        self,
        input_ids: Tensor,
        input_mask: Optional[Tensor] = None,
-        paged_cache: Optional[KvcacheView] = None,
+        paged_cache: Optional[CacheView] = None,
        position_ids: Optional[Tensor] = None,
    ) -> Dict[str, Tensor]:
        assert input_ids.ndim == 2
@@ -132,6 +132,12 @@ class BaseExecutor:
    def grad_accum_steps(self) -> int:
        return self.gradient_state.num_steps

+    def clip_grad_norm(self, model: nn.Module, max_norm: float) -> float:
+        total_norm = torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm)
+        if isinstance(total_norm, torch.Tensor):
+            return total_norm.item()
+        return total_norm
+

 class ExecutorFactory(BaseFactory[BaseExecutor]):
    pass
@@ -260,6 +266,14 @@ class FSDPExecutor(BaseExecutor):
            return model.no_sync()
        return contextlib.nullcontext()

+    def clip_grad_norm(self, model: nn.Module, max_norm: float) -> float:
+        if isinstance(model, FSDP) and self.use_distributed:
+            total_norm = model.clip_grad_norm_(max_norm)
+            if isinstance(total_norm, torch.Tensor):
+                return total_norm.item()
+            return total_norm
+        return super().clip_grad_norm(model, max_norm)
+
    def unwrap_model(self, model: nn.Module):
        if isinstance(model, FSDP) and self.use_distributed:
            with FSDP.state_dict_type(
@@ -58,9 +58,11 @@ def setup_parallel(
    os.environ["WORLD_SIZE"] = str(world_size)
    os.environ["LOCAL_DEVICE"] = str(device_id)

-    dist.init_process_group(
-        rank=rank, world_size=world_size, backend=backend, device_id=device_id
-    )
+    pg_kwargs = dict(rank=rank, world_size=world_size, backend=backend)
+    if backend in ("nccl", "ccl"):
+        pg_kwargs["device_id"] = device_id
+
+    dist.init_process_group(**pg_kwargs)

    try:
        if backend == "nccl" and torch.cuda.is_available():
@@ -144,7 +144,7 @@ class Pipeline:
        for key in list(bucket.keys()):
            if key in result:
                continue
-            bucket[key].append([1] * len(ids))
+            bucket[key].append([0] * len(ids))

    def _iter_items(self):
        for path in self.paths:
@@ -160,6 +160,12 @@ class Pipeline:
            idx = shard_idx[domain]

            pp = self.config.preprocessing
+            original_sequences = keys.get("sequence", [])
+            mode = self.config.output.position_ids_mode
+
+            if mode == "doc_reset" and original_sequences:
+                keys["position_ids"] = [list(range(len(s))) for s in original_sequences]
+
            keys = self._packer.apply(dict(keys), pp.max_packed_len, pp.truncation_mode)

            tensors: Dict[str, List[torch.Tensor]] = {}
@@ -171,9 +177,10 @@ class Pipeline:
                    torch.tensor(list(chain.from_iterable(ids_list)), dtype=dt)
                ]

-            pos_ids = self._position_id.generate(keys.get("sequence", []))
-            if pos_ids:
-                tensors["position_ids"] = [torch.tensor(pos_ids, dtype=torch.int32)]
+            if mode == "continuous" and original_sequences:
+                pos_ids = self._position_id.generate(keys.get("sequence", []))
+                if pos_ids:
+                    tensors["position_ids"] = [torch.tensor(pos_ids, dtype=torch.int32)]

            self._writer.save(self.output_dir, domain, idx, tensors)
            shard_idx[domain] = idx + 1
@@ -14,8 +14,8 @@ from typing import Dict, List

 import torch

-from astrai.dataset.storage import save_bin, save_h5
 from astrai.factory import BaseFactory
+from astrai.serialization import save_bin, save_h5

 logger = logging.getLogger(__name__)

@@ -0,0 +1,43 @@
+"""Serialization utilities for models and datasets.
+
+This package re-exports checkpoint helpers and dataset storage helpers so
+that existing imports from ``astrai.serialization`` continue to work.
+"""
+
+from astrai.serialization.checkpoint import (
+    Checkpoint,
+    load_json,
+    load_model_config,
+    load_model_weights,
+    load_safetensors,
+    load_state_dict,
+    load_torch,
+    save_json,
+    save_model,
+    save_safetensors,
+    save_torch,
+)
+from astrai.serialization.dataset import (
+    load_bin,
+    load_h5,
+    save_bin,
+    save_h5,
+)
+
+__all__ = [
+    "Checkpoint",
+    "load_json",
+    "load_model_config",
+    "load_model_weights",
+    "load_safetensors",
+    "load_state_dict",
+    "load_torch",
+    "save_json",
+    "save_model",
+    "save_safetensors",
+    "save_torch",
+    "load_bin",
+    "load_h5",
+    "save_bin",
+    "save_h5",
+]
@@ -1,5 +1,8 @@
+"""Model checkpoint serialization helpers."""
+
 import io
 import json
+import os
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -136,7 +139,7 @@ def load_state_dict(path: Union[str, Path], broadcast: bool = False) -> dict:
 class Checkpoint:
    state_dict: Dict[str, Any] = field(default_factory=dict)
    epoch: int = 0
-    iteration: int = 0
+    consumed_samples: int = 0
    extra: Dict[str, Any] = field(default_factory=dict)
    meta: Dict[str, Any] = field(default_factory=dict)
    config: Dict[str, Any] = field(default_factory=dict)
@@ -150,7 +153,7 @@ class Checkpoint:

        meta = {
            "epoch": self.epoch,
-            "iteration": self.iteration,
+            "consumed_samples": self.consumed_samples,
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
            **self.meta,
        }
@@ -176,7 +179,7 @@ class Checkpoint:
        return cls(
            state_dict=state_dict,
            epoch=meta.get("epoch", 0),
-            iteration=meta.get("iteration", 0),
+            consumed_samples=meta.get("consumed_samples", 0),
            extra=extra,
            config=config,
        )
@@ -0,0 +1,73 @@
+"""Dataset storage serialization helpers (HDF5 / memory-mapped binary)."""
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, List
+
+import h5py
+import numpy as np
+import torch
+from torch import Tensor
+
+
+def save_h5(file_path: str, file_name: str, tensor_group: Dict[str, List[Tensor]]):
+    os.makedirs(file_path, exist_ok=True)
+    full_file_path = os.path.join(file_path, f"{file_name}.h5")
+    with h5py.File(full_file_path, "w") as f:
+        for key, tensors in tensor_group.items():
+            grp = f.create_group(key)
+            for idx, tensor in enumerate(tensors):
+                arr = tensor.cpu().numpy()
+                grp.create_dataset(f"data_{idx}", data=arr)
+
+
+def load_h5(file_path: str, share_memory=True) -> Dict[str, List[Tensor]]:
+    tensor_group: Dict[str, List[Tensor]] = {}
+
+    root_path = Path(file_path)
+    h5_files = list(root_path.rglob("*.h5")) + list(root_path.rglob("*.hdf5"))
+
+    for h5_file in h5_files:
+        with h5py.File(h5_file, "r") as f:
+            for key in f.keys():
+                grp = f[key]
+                dsets = []
+                for dset_name in grp.keys():
+                    dset = grp[dset_name]
+                    tensor = torch.from_numpy(dset[:])
+                    if share_memory:
+                        tensor = tensor.share_memory_()
+                    dsets.append(tensor)
+
+                if tensor_group.get(key) is None:
+                    tensor_group[key] = []
+                tensor_group[key].extend(dsets)
+
+    return tensor_group
+
+
+def save_bin(file_path: str, tensor_group: Dict[str, List[Tensor]]):
+    os.makedirs(file_path, exist_ok=True)
+    meta = {}
+    for key, tensors in tensor_group.items():
+        cat = torch.cat(tensors, dim=0)
+        meta[key] = {"shape": list(cat.shape), "dtype": str(cat.dtype).split(".")[-1]}
+        np.asarray(cat.cpu().numpy()).tofile(os.path.join(file_path, f"{key}.bin"))
+    with open(os.path.join(file_path, "meta.json"), "w") as f:
+        json.dump(meta, f)
+
+
+def load_bin(file_path: str) -> Dict[str, List[Tensor]]:
+    with open(os.path.join(file_path, "meta.json"), "r") as f:
+        meta = json.load(f)
+    segments: Dict[str, List[Tensor]] = {}
+    for key, info in meta.items():
+        arr = np.memmap(
+            os.path.join(file_path, f"{key}.bin"),
+            dtype=info["dtype"],
+            mode="r+",
+            shape=tuple(info["shape"]),
+        )
+        segments[key] = [torch.from_numpy(arr)]
+    return segments
@@ -1,4 +1,3 @@
-from astrai.trainer.optim import Muon
 from astrai.trainer.schedule import BaseScheduler, SchedulerFactory
 from astrai.trainer.strategy import BaseStrategy, StrategyFactory
 from astrai.trainer.train_callback import (
@@ -10,8 +9,6 @@ from astrai.trainer.trainer import Trainer
 __all__ = [
    # Main trainer
    "Trainer",
-    # Optimizer
-    "Muon",
    # Strategy factory
    "StrategyFactory",
    "BaseStrategy",
@@ -1,42 +1,25 @@
-from typing import Any, Callable, Dict
+from typing import Dict

 import torch
 import torch.nn as nn


-def _grad_stat(
-    model: nn.Module, fn: Callable[[torch.Tensor], Any], default: Any
-) -> dict:
-    results = {}
-    for name, param in model.named_parameters():
-        results[name] = default
-        if param.grad is not None:
-            results[name] = fn(param.grad.data)
-    return results
+def grad_norm(model: nn.Module, per_param: bool = False) -> float | Dict[str, float]:
+    grads = [p.grad.detach() for p in model.parameters() if p.grad is not None]
+    if not grads:
+        return 0.0

-
-def grad_norm(model: nn.Module, norm_type: int = 2) -> Dict[str, float]:
-    return _grad_stat(model, lambda g: g.norm(norm_type).item(), 0.0)
-
-
-def grad_std(model: nn.Module) -> Dict[str, float]:
-    return _grad_stat(model, lambda g: g.std().item(), 0.0)
-
-
-def grad_max(model: nn.Module) -> Dict[str, float]:
-    return _grad_stat(model, lambda g: g.max().item(), -float("inf"))
-
-
-def grad_min(model: nn.Module) -> Dict[str, float]:
-    return _grad_stat(model, lambda g: g.min().item(), float("inf"))
-
-
-def grad_mean(model: nn.Module) -> Dict[str, float]:
-    return _grad_stat(model, lambda g: g.mean().item(), 0.0)
-
-
-def grad_nan_num(model: nn.Module) -> Dict[str, int]:
-    return _grad_stat(model, lambda g: g.isnan().sum().item(), 0)
+    total_sq = torch.stack([g.pow(2).sum() for g in grads]).sum()
+    if per_param:
+        norms = {}
+        for name, param in model.named_parameters():
+            if param.grad is not None:
+                norms[name] = param.grad.norm(2).item()
+            else:
+                norms[name] = 0.0
+        norms["total"] = total_sq.sqrt().item()
+        return norms
+    return total_sq.sqrt().item()


 def ctx_get_loss(ctx):
@@ -52,24 +35,4 @@ def ctx_get_val_loss(ctx):


 def ctx_get_grad_norm(ctx):
-    return grad_norm(ctx.model)
-
-
-def ctx_get_grad_std(ctx):
-    return grad_std(ctx.model)
-
-
-def ctx_get_grad_max(ctx):
-    return grad_max(ctx.model)
-
-
-def ctx_get_grad_min(ctx):
-    return grad_min(ctx.model)
-
-
-def ctx_get_grad_mean(ctx):
-    return grad_mean(ctx.model)
-
-
-def ctx_get_grad_nan_num(ctx):
-    return grad_nan_num(ctx.model)
+    return ctx.grad_norm
@@ -1,143 +0,0 @@
-import torch
-from torch.optim import Optimizer
-
-
-def _zeropower_via_newtonschulz(G: torch.Tensor, steps: int = 5):
-    assert G.ndim == 2
-    X = G
-    scale = max(1, G.size(0) / G.size(1)) ** 0.5
-    X = X / (X.norm() + 1e-7) * scale
-    if steps == 0:
-        return X
-    a, b, c = (3.4445, -4.7750, 2.0315)
-    for _ in range(steps):
-        A = X @ X.T
-        B = A @ X
-        X = a * X + b * B + c * (A @ B)
-    return X
-
-
-class Muon(Optimizer):
-    def __init__(
-        self,
-        params,
-        lr: float = 2e-3,
-        momentum: float = 0.95,
-        weight_decay: float = 0.0,
-        nesterov: bool = True,
-        ns_steps: int = 5,
-        adamw_lr: float = None,
-        adamw_betas: tuple = (0.9, 0.95),
-        adamw_eps: float = 1e-8,
-        adamw_wd: float = 0.0,
-    ):
-        defaults = dict(
-            lr=lr,
-            momentum=momentum,
-            weight_decay=weight_decay,
-            nesterov=nesterov,
-            ns_steps=ns_steps,
-            adamw_lr=adamw_lr if adamw_lr is not None else lr * 0.1,
-            adamw_betas=adamw_betas,
-            adamw_eps=adamw_eps,
-            adamw_wd=adamw_wd,
-        )
-        super().__init__(params, defaults)
-
-    @torch.no_grad()
-    def step(self, closure=None):
-        loss = None
-        if closure is not None:
-            with torch.enable_grad():
-                loss = closure()
-
-        for group in self.param_groups:
-            params_2d, params_1d = [], []
-            grads_2d, grads_1d = [], []
-
-            for p in group["params"]:
-                if p.grad is None:
-                    continue
-                if p.grad.is_sparse:
-                    raise RuntimeError("Muon does not support sparse gradients")
-                if p.ndim >= 2:
-                    params_2d.append(p)
-                    grads_2d.append(p.grad)
-                else:
-                    params_1d.append(p)
-                    grads_1d.append(p.grad)
-
-            if params_2d:
-                self._muon_update_foreach(params_2d, grads_2d, group)
-            if params_1d:
-                self._adamw_update_foreach(params_1d, grads_1d, group)
-
-        return loss
-
-    def _muon_update_foreach(self, params_2d, grads_2d, group):
-        lr = group["lr"]
-        momentum = group["momentum"]
-        wd = group["weight_decay"]
-        nesterov = group["nesterov"]
-        ns_steps = group["ns_steps"]
-
-        if wd != 0:
-            torch._foreach_mul_(params_2d, 1 - lr * wd)
-
-        if nesterov:
-            grads_2d = torch._foreach_add(grads_2d, params_2d, alpha=wd)
-
-        bufs = []
-        for p, grad in zip(params_2d, grads_2d):
-            state = self.state[p]
-            if "momentum_buffer" not in state:
-                state["momentum_buffer"] = torch.zeros_like(grad)
-            bufs.append(state["momentum_buffer"])
-
-        torch._foreach_lerp_(bufs, grads_2d, 1 - momentum)
-
-        for p, buf in zip(params_2d, bufs):
-            update = _zeropower_via_newtonschulz(buf, steps=ns_steps)
-            scale = max(1, p.size(0) / p.size(1)) ** 0.5
-            p.add_(update, alpha=-lr * scale)
-
-    def _adamw_update_foreach(self, params_1d, grads_1d, group):
-        lr = group["adamw_lr"]
-        betas = group["adamw_betas"]
-        eps = group["adamw_eps"]
-        wd = group["adamw_wd"]
-
-        steps: list[int] = []
-        exp_avgs, exp_avg_sqs = [], []
-        has_state = []
-        for p in params_1d:
-            state = self.state[p]
-            if not state:
-                state["step"] = 0
-                state["exp_avg"] = torch.zeros_like(p)
-                state["exp_avg_sq"] = torch.zeros_like(p)
-                has_state.append(False)
-            else:
-                has_state.append(True)
-            state["step"] += 1
-            steps.append(state["step"])
-            exp_avgs.append(state["exp_avg"])
-            exp_avg_sqs.append(state["exp_avg_sq"])
-
-        beta1, beta2 = betas
-
-        torch._foreach_lerp_(exp_avgs, grads_1d, 1 - beta1)
-        grads_sq = torch._foreach_mul(grads_1d, grads_1d)
-        torch._foreach_lerp_(exp_avg_sqs, grads_sq, 1 - beta2)
-
-        bias_correction1 = [1 - beta1**s for s in steps]
-        bias_correction2 = [1 - beta2**s for s in steps]
-
-        if wd != 0:
-            torch._foreach_mul_(params_1d, 1 - lr * wd)
-
-        exp_avg_corrected = torch._foreach_div(exp_avgs, bias_correction1)
-        denom = torch._foreach_div(exp_avg_sqs, bias_correction2)
-        denom = torch._foreach_sqrt(denom)
-        torch._foreach_add_(denom, eps)
-        torch._foreach_addcdiv_(params_1d, exp_avg_corrected, denom, value=-lr)
@@ -53,7 +53,7 @@ class CosineScheduler(BaseScheduler):
        optimizer,
        warmup_steps: int,
        lr_decay_steps: int,
-        min_rate: float = 0.05,
+        min_rate: float = 0.01,
        last_epoch: int = -1,
    ):
        self.warmup_steps = warmup_steps
@@ -65,11 +65,15 @@ class CosineScheduler(BaseScheduler):
    def get_lr(self) -> List[float]:
        # warmup
        if self.last_epoch < self.warmup_steps:
-            warmup_factor = max(self.min_rate, self.last_epoch / self.warmup_steps)
+            warmup_factor = max(
+                self.min_rate, self.last_epoch / max(self.warmup_steps, 1)
+            )
            return [base_lr * warmup_factor for base_lr in self.base_lrs]

        # cosine decay
-        decay_progress = (self.last_epoch - self.warmup_steps) / self.lr_decay_steps
+        decay_progress = (self.last_epoch - self.warmup_steps) / max(
+            self.lr_decay_steps, 1
+        )
        decay_progress = min(decay_progress, 1.0)
        cosine_decay = 0.5 * (1.0 + math.cos(math.pi * decay_progress))
        decay_factor = max(self.min_rate, cosine_decay)
@@ -104,7 +108,7 @@ class SGDRScheduler(BaseScheduler):
        optimizer,
        warmup_steps: int,
        cycle_length: int,
-        min_rate: float = 0.05,
+        min_rate: float = 0.01,
        t_mult: int = 2,
        last_epoch: int = -1,
    ):
@@ -118,7 +122,9 @@ class SGDRScheduler(BaseScheduler):
    def get_lr(self):
        # warmup
        if self.last_epoch < self.warmup_steps:
-            warmup_factor = max(self.min_rate, self.last_epoch / self.warmup_steps)
+            warmup_factor = max(
+                self.min_rate, self.last_epoch / max(self.warmup_steps, 1)
+            )
            return [base_lr * warmup_factor for base_lr in self.base_lrs]

        # SGDR
@@ -182,7 +188,7 @@ class WSDScheduler(BaseScheduler):
        warmup_steps: int,
        stable_steps: int,
        decay_steps: int,
-        min_rate: float = 0.0,
+        min_rate: float = 0.01,
        last_epoch: int = -1,
    ):
        self.warmup_steps = warmup_steps
@@ -194,7 +200,7 @@ class WSDScheduler(BaseScheduler):

    def get_lr(self) -> List[float]:
        if self.last_epoch < self.warmup_steps:
-            factor = self.last_epoch / max(self.warmup_steps, 1)
+            factor = max(self.min_rate, self.last_epoch / max(self.warmup_steps, 1))
            return [base_lr * factor for base_lr in self.base_lrs]

        offset = self.last_epoch - self.warmup_steps
@@ -196,7 +196,7 @@ class SFTStrategy(BaseStrategy):

        ignore_index = -100
        input_mask = make_doc_boundary_mask(position_ids)
-        target_ids = target_ids.masked_fill(loss_mask == 0, ignore_index)
+        target_ids = target_ids.masked_fill(~loss_mask, ignore_index)
        logits = self.model(
            input_ids=input_ids, position_ids=position_ids, input_mask=input_mask
        )["logits"]
@@ -9,7 +9,6 @@ from typing import IO, Callable, List, Optional, Protocol, runtime_checkable
 import torch
 import torch.distributed as dist
 import torch.nn as nn
-from torch.nn.utils import clip_grad_norm_
 from torch.utils.checkpoint import checkpoint as torch_checkpoint
 from tqdm import tqdm

@@ -18,12 +17,7 @@ from astrai.parallel import only_on_rank
 from astrai.parallel.setup import get_current_device, get_rank
 from astrai.serialization import Checkpoint
 from astrai.trainer.metric_util import (
-    ctx_get_grad_max,
-    ctx_get_grad_mean,
-    ctx_get_grad_min,
-    ctx_get_grad_nan_num,
    ctx_get_grad_norm,
-    ctx_get_grad_std,
    ctx_get_loss,
    ctx_get_lr,
    ctx_get_val_loss,
@@ -86,7 +80,9 @@ class GradientClippingCallback(TrainCallback):
        self.max_grad_norm = max_grad_norm

    def on_optimizer_step(self, context: TrainContext):
-        clip_grad_norm_(context.model.parameters(), self.max_grad_norm)
+        context.grad_norm = context.executor.clip_grad_norm(
+            context.model, self.max_grad_norm
+        )


@CallbackFactory.register("gradient_checkpointing")
@@ -143,34 +139,35 @@ class CheckpointCallback(TrainCallback):
        self.interval = interval
        self.weight_only = weight_only
        self.save_extra_fn = save_extra_fn or CheckpointCallback.save_extra
-        self.last_ckpt_iter = 0
+        self.last_ckpt_step = 0

    def _save_checkpoint(self, context: TrainContext):
        state_dict = context.executor.unwrap_model(context.model)
-        self.last_ckpt_iter = context.iteration
+        self.last_ckpt_step = context.optimizer_step

        if get_rank() == 0:
            save_path = os.path.join(
-                self.save_dir, f"epoch_{context.epoch}_iter_{context.iteration}"
+                self.save_dir,
+                f"epoch_{context.epoch}_step_{context.optimizer_step}",
            )
            extra = self.save_extra_fn(context)
            meta = context.config.to_dict()
            context.checkpoint = Checkpoint(
                state_dict=state_dict,
                epoch=context.epoch,
-                iteration=context.iteration,
+                consumed_samples=context.consumed_samples,
+                config=context.model_config,
                extra=extra,
                meta=meta,
-                config=context.model_config,
            )
            context.checkpoint.save(save_path)

    def on_batch_end(self, context: TrainContext):
-        if context.iteration - self.last_ckpt_iter >= self.interval:
+        if context.optimizer_step - self.last_ckpt_step >= self.interval:
            self._save_checkpoint(context)

    def on_train_end(self, context: TrainContext):
-        if context.iteration != self.last_ckpt_iter:
+        if context.optimizer_step != self.last_ckpt_step:
            self._save_checkpoint(context)

    def on_error(self, context: TrainContext):
@@ -202,23 +199,27 @@ class ProgressBarCallback(TrainCallback):

    @only_on_rank(0)
    def on_epoch_begin(self, context: TrainContext):
+        total_steps = len(context.dataloader) // context.executor.grad_accum_steps
        self.progress_bar = tqdm(
-            context.dataloader,
+            total=total_steps,
            desc=f"Epoch {context.epoch + 1}/{self.num_epoch}",
            dynamic_ncols=True,
            file=self.file or sys.stdout,
        )

    @only_on_rank(0)
-    def on_batch_end(self, context: TrainContext):
+    def on_optimizer_step(self, context: TrainContext):
+        self.progress_bar.update(1)
        postfix = {
+            "step": context.optimizer_step,
            "loss": f"{context.loss:.4f}",
            "lr": f"{context.optimizer.param_groups[-1]['lr']:.2e}",
        }
+        if context.grad_norm is not None:
+            postfix["grad_norm"] = f"{context.grad_norm:.2f}"
        if context.val_loss is not None:
            postfix["val_loss"] = f"{context.val_loss:.4f}"
        self.progress_bar.set_postfix(postfix)
-        self.progress_bar.update(1)

    @only_on_rank(0)
    def on_epoch_end(self, context: TrainContext):
@@ -227,20 +228,20 @@ class ProgressBarCallback(TrainCallback):
            self.progress_bar.close()


-@CallbackFactory.register("metric_logger")
-class MetricLoggerCallback(TrainCallback):
+@CallbackFactory.register("metric")
+class MetricCallback(TrainCallback):
    def __init__(
        self,
        log_dir: str,
        save_interval: int,
-        log_interval: int = 10,
        metrics: List[str] = None,
+        val_step: int = 0,
    ):
-        self.last_log_iter = 0
-        self._last_val_loss = None
+        self.last_log_flush_step = 0
        self.save_interval = save_interval
-        self.log_interval = log_interval
        self.metrics = metrics or ["loss", "lr"]
+        self.val_step = val_step
+        self._next_val_step = 0

        self.log_dir = Path(log_dir) if log_dir else Path.cwd() / "logs"
        self.log_dir.mkdir(parents=True, exist_ok=True)
@@ -252,11 +253,6 @@ class MetricLoggerCallback(TrainCallback):
            "lr": ctx_get_lr,
            "val_loss": ctx_get_val_loss,
            "grad_norm": ctx_get_grad_norm,
-            "grad_std": ctx_get_grad_std,
-            "grad_max": ctx_get_grad_max,
-            "grad_min": ctx_get_grad_min,
-            "grad_mean": ctx_get_grad_mean,
-            "grad_nan_num": ctx_get_grad_nan_num,
        }

    def _metrics(self, context: TrainContext, names):
@@ -272,46 +268,13 @@ class MetricLoggerCallback(TrainCallback):
            "type": event_type,
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
            "epoch": context.epoch,
-            "iter": context.iteration,
+            "step": context.optimizer_step,
+            "consumed_samples": context.consumed_samples,
            **extra,
        }
        self.log_cache.append(entry)

-    @only_on_rank(0)
-    def _flush(self, epoch, iter):
-        log_file = self.log_dir / f"epoch_{epoch}_iter_{iter}_metric.jsonl"
-        log_file.parent.mkdir(parents=True, exist_ok=True)
-        with open(log_file, "w") as f:
-            for log in self.log_cache:
-                f.write(json.dumps(log) + "\n")
-
-    def on_batch_end(self, context):
-        if context.iteration % self.log_interval == 0:
-            step_metrics = [m for m in self.metrics if m != "val_loss"]
-            self._append("step", context, **self._metrics(context, step_metrics))
-        if context.iteration - self.last_log_iter >= self.save_interval:
-            self._flush(context.epoch, context.iteration)
-            self.last_log_iter = context.iteration
-
-    def on_optimizer_step(self, context):
-        if context.val_loss is not None and context.val_loss != self._last_val_loss:
-            self._append("validation", context, val_loss=context.val_loss)
-            self._last_val_loss = context.val_loss
-
-    def on_epoch_end(self, context):
-        self._append("epoch", context)
-
-    def on_train_end(self, context):
-        if context.iteration != self.last_log_iter:
-            self._flush(context.epoch, context.iteration)
-
-    def on_error(self, context):
-        self._flush(context.epoch, context.iteration)
-
-
-@CallbackFactory.register("validation")
-class ValidationCallback(TrainCallback):
-    def _run_validation(self, context: TrainContext):
+    def _run_validation(self, context: TrainContext) -> float:
        context.model.eval()

        total_loss = 0.0
@@ -323,27 +286,49 @@ class ValidationCallback(TrainCallback):
                total_loss += loss.item()
                num_batches += 1

-        avg_loss = total_loss / max(num_batches, 1)
-
        if context.world_size > 1 and dist.is_initialized():
-            loss_tensor = torch.tensor([avg_loss], device=get_current_device())
-            dist.all_reduce(loss_tensor, op=dist.ReduceOp.AVG)
-            avg_loss = loss_tensor.item()
+            stats = torch.tensor(
+                [total_loss, float(num_batches)], device=get_current_device()
+            )
+            dist.all_reduce(stats, op=dist.ReduceOp.SUM)
+            avg_loss = (stats[0] / stats[1]).item()
+        else:
+            avg_loss = total_loss / max(num_batches, 1)

-        context.val_loss = avg_loss
        context.model.train()
+        return avg_loss

-        step_count = context.iteration // context.config.grad_accum_steps
-        logger.info(
-            f"Epoch {context.epoch + 1}, Step {step_count}, Val Loss: {avg_loss:.4f}"
-        )
+    @only_on_rank(0)
+    def _flush(self, epoch, step):
+        log_file = self.log_dir / f"epoch_{epoch}_step_{step}_metric.jsonl"
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_file, "w") as f:
+            for log in self.log_cache:
+                f.write(json.dumps(log) + "\n")

-    def on_optimizer_step(self, context: TrainContext):
-        if context.val_dataloader is None:
-            return
-        cfg = context.config
-        if cfg.val_step <= 0:
-            return
-        step_count = context.iteration // cfg.grad_accum_steps
-        if step_count % cfg.val_step == 0:
-            self._run_validation(context)
+    def on_optimizer_step(self, context):
+        if (
+            context.val_dataloader is not None
+            and self.val_step > 0
+            and context.optimizer_step >= self._next_val_step
+        ):
+            context.val_loss = self._run_validation(context)
+            self._next_val_step = context.optimizer_step + self.val_step
+            self._append("validation", context, val_loss=context.val_loss)
+
+        step_metrics = [m for m in self.metrics if m != "val_loss"]
+        self._append("step", context, **self._metrics(context, step_metrics))
+
+        if context.optimizer_step - self.last_log_flush_step >= self.save_interval:
+            self._flush(context.epoch, context.optimizer_step)
+            self.last_log_flush_step = context.optimizer_step
+
+    def on_epoch_end(self, context):
+        self._append("epoch", context)
+
+    def on_train_end(self, context):
+        if context.optimizer_step != self.last_log_flush_step:
+            self._flush(context.epoch, context.optimizer_step)
+
+    def on_error(self, context):
+        self._flush(context.epoch, context.optimizer_step)
@@ -29,8 +29,9 @@ class TrainContext:
    executor: BaseExecutor = field(default=None)

    epoch: int = field(default=0)
-    iteration: int = field(default=0)
+    consumed_samples: int = field(default=0)
    loss: float = field(default=0.0)
+    grad_norm: Optional[float] = field(default=None)
    val_dataloader: Optional[DataLoader] = field(default=None)
    val_loss: Optional[float] = field(default=None)

@@ -38,6 +39,14 @@ class TrainContext:
    rank: int = field(default=0)
    kwargs: Dict[str, Any] = field(default_factory=dict)

+    @property
+    def optimizer_step(self) -> int:
+        return self.consumed_samples // (
+            self.config.batch_per_device
+            * self.world_size
+            * self.config.grad_accum_steps
+        )
+

 class TrainContextBuilder:
    def __init__(
@@ -89,7 +98,10 @@ class TrainContextBuilder:
                if checkpoint.config:
                    context.model_config = checkpoint.config
                context.epoch = checkpoint.epoch or cfg.start_epoch
-                context.iteration = checkpoint.iteration or cfg.start_batch
+                if checkpoint.consumed_samples > 0:
+                    context.consumed_samples = checkpoint.consumed_samples
+                else:
+                    context.consumed_samples = cfg.start_samples * context.world_size
                context.checkpoint = checkpoint

        if cfg.lora is not None:
@@ -115,7 +127,7 @@ class TrainContextBuilder:
                cfg.dataset, [n_train, n_val], generator=generator
            )

-        sampler_offset = context.iteration * cfg.batch_per_device
+        sampler_offset = context.consumed_samples // context.world_size
        sampler = ResumableDistributedSampler(
            data_source=train_dataset,
            start_epoch=context.epoch,
@@ -34,13 +34,12 @@ class Trainer:
                cfg.ckpt_dir,
                cfg.ckpt_interval,
            ),
-            CallbackFactory.create("validation"),
            CallbackFactory.create(
-                "metric_logger",
+                "metric",
                log_dir=cfg.log_dir,
                save_interval=cfg.ckpt_interval,
-                log_interval=cfg.log_interval,
                metrics=cfg.metrics,
+                val_step=cfg.val_step,
            ),
            CallbackFactory.create("progress_bar", cfg.n_epoch),
            CallbackFactory.create("gradient_clipping", cfg.max_grad_norm),
@@ -74,7 +73,9 @@ class Trainer:
                        context.loss = loss.item()
                        stand_loss = loss / executor.grad_accum_steps
                        executor.backward(stand_loss)
-                        context.iteration += 1
+                        context.consumed_samples += (
+                            context.config.batch_per_device * context.world_size
+                        )
                        self._call_callbacks("on_batch_end", context)

                        if executor.sync_gradients:
@@ -9,8 +9,8 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
    "h5py==3.15.1",
-    "numpy==2.3.2",
-    "torch==2.7.1",
+    "numpy==2.4.4",
+    "torch==2.11.0",
    "tokenizers==0.21.4",
    "tqdm==4.67.1",
    "safetensors==0.5.3",
@@ -37,7 +37,7 @@ dev = ["pytest==9.0.2", "ruff"]
 where = ["."]

 [tool.pip]
-extra-index-url = "https://download.pytorch.org/whl/cu126"
+extra-index-url = "https://download.pytorch.org/whl/cu128"

 [tool.setuptools.dynamic]
 version = { attr = "astrai.__version__" }
@@ -1,3 +1,4 @@
+from argparse import ArgumentParser
 from pathlib import Path

 import torch
@@ -7,42 +8,82 @@ from astrai.model import AutoModel
 from astrai.tokenize import AutoTokenizer

 PROJECT_ROOT = Path(__file__).resolve().parents[2]
-PARAMETER_ROOT = Path(PROJECT_ROOT, "params")
+
+
+def parse_args():
+    parser = ArgumentParser(description="Interactive streaming chat")
+    parser.add_argument(
+        "--model_path",
+        type=Path,
+        default=PROJECT_ROOT / "params",
+        help="Path to model weights (params/ or checkpoint/epoch_N_step_M/)",
+    )
+    parser.add_argument(
+        "--temperature",
+        type=float,
+        default=0.8,
+        help="Sampling temperature (default: 0.8)",
+    )
+    parser.add_argument(
+        "--top_p",
+        type=float,
+        default=0.95,
+        help="Top-p sampling threshold",
+    )
+    parser.add_argument(
+        "--top_k",
+        type=int,
+        default=50,
+        help="Top-k sampling threshold",
+    )
+    parser.add_argument(
+        "--max_tokens",
+        type=int,
+        default=2048,
+        help="Maximum tokens to generate",
+    )
+    parser.add_argument(
+        "--system_prompt",
+        type=str,
+        default="You are a helpful assistant.",
+        help="Optional system prompt",
+    )
+    return parser.parse_args()


 def chat():
-    model = AutoModel.from_pretrained(PARAMETER_ROOT)
-    tokenizer = AutoTokenizer.from_pretrained(PARAMETER_ROOT)
-    model.to(device="cuda", dtype=torch.bfloat16)
+    args = parse_args()
+    model_path = args.model_path

-    messages = [{"role": "system", "content": "You are a helpful assistant."}]
+    model = AutoModel.from_pretrained(model_path)
+    tokenizer = AutoTokenizer.from_pretrained(model_path)
+    model.to(device="cuda", dtype=torch.bfloat16)
    engine = InferenceEngine(model=model, tokenizer=tokenizer)

+    messages = [{"role": "system", "content": args.system_prompt}]
+
    while True:
        query = input(">> ")
        if query == "!exit":
            break

-        # Add user message
        messages.append({"role": "user", "content": query})

-        # Generate response
        full_response = ""
        prompt = tokenizer.apply_chat_template(messages, tokenize=False)

        for token in engine.generate(
            prompt=prompt,
            stream=True,
-            max_tokens=2048,
-            temperature=0.8,
-            top_p=0.95,
-            top_k=50,
+            max_tokens=args.max_tokens,
+            temperature=args.temperature,
+            top_p=args.top_p,
+            top_k=args.top_k,
        ):
            print(token, end="", flush=True)
            full_response += token

        print()
-        # Add assistant response to messages
        messages.append({"role": "assistant", "content": full_response.strip()})


@@ -0,0 +1,307 @@
+"""SVD effective rank & weight statistics analysis for model checkpoints."""
+
+import argparse
+import json
+from pathlib import Path
+
+import safetensors.torch
+import torch
+
+
+def effective_rank_metrics(w: torch.Tensor) -> dict:
+    if w.ndim == 1:
+        return {"shape": tuple(w.shape), "is_1d": True}
+
+    w = w.float()
+    s = torch.linalg.svdvals(w)
+    s_sq = s**2
+    total = s_sq.sum()
+    cumsum = torch.cumsum(s_sq, dim=0) / total
+
+    min_dim = min(w.shape[0], w.shape[1])
+    er_90 = (cumsum < 0.90).sum().item() + 1
+    er_95 = (cumsum < 0.95).sum().item() + 1
+    er_99 = (cumsum < 0.99).sum().item() + 1
+
+    p = s_sq / total
+    p = p[p > 1e-30]
+    entropy = -(p * torch.log(p)).sum()
+    entropic_rank = torch.exp(entropy).item()
+
+    return {
+        "shape": tuple(w.shape),
+        "min_dim": min_dim,
+        "er_90": er_90,
+        "er_95": er_95,
+        "er_99": er_99,
+        "er_99_norm": er_99 / min_dim,
+        "er_95_norm": er_95 / min_dim,
+        "entropic_rank": entropic_rank,
+        "entropic_rank_norm": entropic_rank / min_dim,
+        "top1_ratio": s[0].item() / s.sum().item(),
+        "top5_ratio": s[:5].sum().item() / s.sum().item(),
+        "decay_ratio": s[-1].item() / s[0].item(),
+        "condition_number": s[0].item() / s[-1].item(),
+        "mean": w.mean().item(),
+        "std": w.std().item(),
+        "min": w.min().item(),
+        "max": w.max().item(),
+    }
+
+
+def format_header(headers: list[str], widths: list[int]) -> str:
+    return "".join(h.ljust(w) for h, w in zip(headers, widths))
+
+
+def format_row(values: list[str], widths: list[int]) -> str:
+    return "".join(v.ljust(w) for v, w in zip(values, widths))
+
+
+def group_by_component(results: dict[str, dict]) -> dict[str, list[dict]]:
+    groups: dict[str, list[dict]] = {}
+    for key, r in results.items():
+        parts = key.split(".")
+        if parts[0] == "layers" and len(parts) >= 3:
+            sub = parts[2:]
+            if sub[0] == "attention":
+                comp = f"attn.{sub[1]}"
+            elif sub[0] == "mlp":
+                comp = f"mlp.{sub[1]}"
+            elif sub[0] == "input_norm":
+                comp = "input_norm"
+            elif sub[0] == "post_attention_norm":
+                comp = "post_attn_norm"
+            else:
+                comp = ".".join(sub)
+        else:
+            comp = key
+        groups.setdefault(comp, []).append(r)
+    return groups
+
+
+def print_component_summary(results: dict[str, dict], title: str):
+    groups = group_by_component(results)
+    matrix_groups = {
+        k: [v for v in vs if not v.get("is_1d")]
+        for k, vs in groups.items()
+        if any(not v.get("is_1d") for v in vs)
+    }
+
+    widths = [20, 12, 12, 12, 12, 12]
+    print(f"\n{title}")
+    print(
+        format_header(
+            ["Component", "N", "ER@99%", "EntRank%", "Top1 σ(%)", "Cond. Num"], widths
+        )
+    )
+    print("-" * sum(widths))
+
+    for name in sorted(matrix_groups.keys()):
+        items = matrix_groups[name]
+        n = len(items)
+        print(
+            format_row(
+                [
+                    name,
+                    str(n),
+                    f"{sum(r['er_99_norm'] for r in items) / n:.4f}",
+                    f"{sum(r['entropic_rank_norm'] for r in items) / n:.4f}",
+                    f"{sum(r['top1_ratio'] for r in items) / n:.4f}",
+                    f"{sum(r['condition_number'] for r in items) / n:.1f}",
+                ],
+                widths,
+            )
+        )
+
+    all_er = [
+        r["er_99_norm"]
+        for vs in matrix_groups.values()
+        for r in vs
+        if "_norm" not in r or not r.get("is_1d")
+    ]
+    if all_er:
+        m = sum(all_er) / len(all_er)
+        print(f"\n  Overall Mean ER@99: {m:.4f} ({m * 100:.1f}% of dimension)")
+        if m > 0.85:
+            print("  → HIGH utilization: model near capacity → need more params")
+        elif m > 0.5:
+            print("  → MODERATE utilization: some headroom left")
+        else:
+            print("  → LOW utilization: significant unused capacity")
+
+
+def print_layer_grid(results: dict[str, dict]):
+    comps = [
+        "attn.q_proj",
+        "attn.k_proj",
+        "attn.v_proj",
+        "attn.o_proj",
+        "mlp.up",
+        "mlp.gate",
+        "mlp.down",
+    ]
+    widths = [6] + [10] * len(comps)
+    metric = "er_99_norm"
+
+    print(f"\n--- Per-Layer Effective Rank (99% energy) ---")
+    print(format_header(["Layer"] + comps, widths))
+    print("-" * sum(widths))
+
+    layer_data: dict[int, dict[str, dict]] = {}
+    for key, r in results.items():
+        parts = key.split(".")
+        if parts[0] != "layers":
+            continue
+        li = int(parts[1])
+        sub = parts[2:]
+        if sub[0] == "attention":
+            cname = f"attn.{sub[1]}"
+        elif sub[0] == "mlp":
+            cname = f"mlp.{sub[1]}"
+        else:
+            continue
+        layer_data.setdefault(li, {})[cname] = r
+
+    for li in sorted(layer_data):
+        values = [str(li)]
+        for c in comps:
+            v = layer_data[li].get(c, {}).get(metric, 0)
+            values.append(f"{v:.4f}")
+        print(format_row(values, widths))
+
+
+def print_weight_stats(results: dict[str, dict]):
+    groups = group_by_component(results)
+    widths = [20, 12, 12, 12, 12]
+    print(f"\n--- Weight Value Statistics ---")
+    print(format_header(["Component", "Mean", "Std", "Min", "Max"], widths))
+    print("-" * sum(widths))
+
+    for name in sorted(groups.keys()):
+        items = groups[name]
+        means = [r.get("mean", 0) for r in items]
+        stds = [r.get("std", 0) for r in items]
+        mins = [r.get("min", 0) for r in items]
+        maxs = [r.get("max", 0) for r in items]
+        g_mean = sum(means) / len(means)
+        g_std = sum(stds) / len(stds)
+        g_min = min(mins)
+        g_max = max(maxs)
+        print(
+            format_row(
+                [
+                    name,
+                    f"{g_mean:.6f}",
+                    f"{g_std:.6f}",
+                    f"{g_min:.6f}",
+                    f"{g_max:.6f}",
+                ],
+                widths,
+            )
+        )
+
+
+def print_params_summary(results: dict[str, dict]):
+    total_2d = sum(
+        r["shape"][0] * r["shape"][1] for r in results.values() if not r.get("is_1d")
+    )
+    total_1d = sum(r["shape"][0] for r in results.values() if r.get("is_1d"))
+    print(f"\n  Total 2D params: {total_2d:,}")
+    print(f"  Total 1D params: {total_1d:,}")
+    print(f"  Total params:     {total_2d + total_1d:,}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SVD effective rank & weight statistics of a model checkpoint."
+    )
+    parser.add_argument(
+        "--ckpt_dir",
+        type=str,
+        required=True,
+        help="Path to checkpoint directory (containing model.safetensors + config.json).",
+    )
+    parser.add_argument(
+        "--compare",
+        type=str,
+        nargs="*",
+        help="Additional checkpoint directories to compare against.",
+    )
+    parser.add_argument(
+        "--no_svd",
+        action="store_true",
+        help="Skip SVD analysis, only show weight statistics (mean/std/min/max).",
+    )
+    args = parser.parse_args()
+
+    def analyze_one(ckpt_dir: str, label: str):
+        ckpt_dir = Path(ckpt_dir)
+        weights_path = ckpt_dir / "model.safetensors"
+        if not weights_path.exists():
+            print(f"ERROR: {weights_path} not found")
+            return {}
+
+        meta = {}
+        meta_path = ckpt_dir / "meta.json"
+        if meta_path.exists():
+            with open(meta_path) as f:
+                meta = json.load(f)
+
+        print(f"\n{'=' * 70}")
+        print(f"  {label}: {ckpt_dir}")
+        if meta:
+            print(
+                f"  Iteration: {meta.get('iteration', '?')}, "
+                f"Strategy: {meta.get('strategy', '?')}, "
+                f"nprocs={meta.get('nprocs', '?')}"
+            )
+        print(f"{'=' * 70}")
+
+        print(f"Loading weights...")
+        sd = safetensors.torch.load_file(str(weights_path))
+        print(f"  {len(sd)} keys loaded")
+
+        weight_keys = [
+            k
+            for k in sd
+            if ".weight" in k and "rotary_embedding" not in k and "freqs_cis" not in k
+        ]
+
+        results = {}
+        if not args.no_svd:
+            print(f"Computing SVD on {len(weight_keys)} tensors...")
+            for i, k in enumerate(sorted(weight_keys)):
+                print(f"  [{i + 1}/{len(weight_keys)}] {k:<60s}", end="\r")
+                results[k] = effective_rank_metrics(sd[k])
+            print()
+        else:
+            print(f"Computing stats on {len(weight_keys)} tensors (no SVD)...")
+            for i, k in enumerate(sorted(weight_keys)):
+                t = sd[k]
+                results[k] = {
+                    "shape": tuple(t.shape),
+                    "is_1d": t.ndim == 1,
+                    "mean": t.float().mean().item(),
+                    "std": t.float().std().item(),
+                    "min": t.float().min().item(),
+                    "max": t.float().max().item(),
+                }
+
+        print_params_summary(results)
+        if not args.no_svd:
+            print_component_summary(
+                results, "\n=== SVD Effective Rank by Component ==="
+            )
+            print_layer_grid(results)
+        print_weight_stats(results)
+        return results
+
+    analyze_one(args.ckpt_dir, "Primary")
+
+    if args.compare:
+        for cdir in args.compare:
+            analyze_one(cdir, "Compare")
+
+
+if __name__ == "__main__":
+    main()
@@ -1,22 +1,22 @@
-"""HumanEval code generation benchmark.
+"""HumanEval benchmark — functional pipeline design.

-Generates n completions per problem, extracts function bodies, executes
-against hidden tests, and computes pass@k.
+Pipeline:
+    load -> generate -> extract -> test -> score -> report

-Usage::
-
-    python scripts/tools/evaluate_humaneval.py --param_path ./params \
-        --data_path HumanEval.jsonl.gz --output results.json \
-        --num_samples 200 --temperature 0.8 --max_tokens 512
+Each stage is a pure function (except GPU/CPU-bound I/O stages).
+Config is a single dataclass; side effects are isolated at pipeline boundaries.
 """

 import argparse
+import itertools
 import json
 import os
 import re
+import subprocess
+import sys
+from dataclasses import dataclass
 from math import prod
-from multiprocessing import Process, Queue
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, Iterator, List, Optional, Sequence, Tuple

 import numpy as np
 import torch
@@ -26,11 +26,15 @@ from astrai.inference import InferenceEngine
 from astrai.model import AutoModel
 from astrai.tokenize import AutoTokenizer

+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
 HUMANEVAL_URL = (
    "https://github.com/openai/human-eval/raw/master/data/HumanEval.jsonl.gz"
 )

-_STOP_SEQUENCES = [
+STOP_SEQUENCES = [
    "\nclass ",
    "\ndef ",
    "\n# ",
@@ -40,43 +44,85 @@ _STOP_SEQUENCES = [
 ]


-def _download_humaneval(data_path: str):
-    if os.path.exists(data_path):
+@dataclass
+class EvalConfig:
+    param_path: str = "./params"
+    data_path: str = "./humaneval/HumanEval.jsonl"
+    output: Optional[str] = None
+
+    test_only: Optional[str] = None
+    generate_only: bool = False
+
+    num_samples: int = 200
+    max_tokens: int = 512
+    temperature: float = 0.8
+    top_p: float = 0.95
+    top_k: int = 50
+    batch_size: int = 32
+    test_timeout: float = 3.0
+    test_workers: int = 8
+    k_values: Tuple[int, ...] = (1, 10, 100)
+    problem_indices: Optional[List[int]] = None
+
+
+def download(url: str, path: str):
+    if os.path.exists(path):
        return
    import gzip
    import urllib.request

-    os.makedirs(os.path.dirname(data_path) or ".", exist_ok=True)
-    print(f"Downloading HumanEval from {HUMANEVAL_URL} ...")
-    tmp = data_path + ".tmp"
-    urllib.request.urlretrieve(HUMANEVAL_URL, tmp)
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    print(f"Downloading {url} ...")
+    tmp = path + ".tmp"
+    urllib.request.urlretrieve(url, tmp)
    with gzip.open(tmp, "rb") as f_in:
-        with open(data_path, "wb") as f_out:
+        with open(path, "wb") as f_out:
            f_out.write(f_in.read())
    os.remove(tmp)
-    print(f"  saved to {data_path}")
+    print(f"  saved to {path}")


-def _load_problems(data_path: str) -> List[dict]:
-    problems = []
-    with open(data_path, "r", encoding="utf-8") as f:
+def load_jsonl(path: str) -> List[dict]:
+    rows = []
+    with open(path, encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if line:
-                problems.append(json.loads(line))
-    return problems
+                rows.append(json.loads(line))
+    return rows


-def _extract_function_body(code: str, entry_point: str) -> Optional[str]:
-    """Extract the function body from a completion."""
+def save_json(path: str, data):
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+
+
+def create_engine(param_path: str, batch_size: int) -> InferenceEngine:
+    model = AutoModel.from_pretrained(param_path)
+    tokenizer = AutoTokenizer.from_pretrained(param_path)
+    model.to(device="cuda", dtype=torch.bfloat16)
+    return InferenceEngine(
+        model=model,
+        tokenizer=tokenizer,
+        max_batch_size=batch_size,
+    )
+
+
+def trim_stop(text: str) -> str:
+    for stop in STOP_SEQUENCES:
+        idx = text.find(stop)
+        if idx != -1:
+            text = text[:idx]
+    return text
+
+
+def extract_body(code: str, entry_point: str) -> Optional[str]:
    pattern = rf"def\s+{re.escape(entry_point)}\b[^:]*:"
    match = re.search(pattern, code)
    if not match:
-        # Use the full code as-is if we can't find the function
        return code

-    body_start = match.end()
-    lines = code[body_start:].split("\n")
+    lines = code[match.end() :].split("\n")
    body_lines = []
    started = False

@@ -94,240 +140,253 @@ def _extract_function_body(code: str, entry_point: str) -> Optional[str]:
        body_lines.append(stripped)

    body = "\n".join(body_lines)
-    if not body.strip():
-        return None
-    return body
+    return body if body.strip() else None


-def _trim_stop_sequences(text: str) -> str:
-    for stop in _STOP_SEQUENCES:
-        idx = text.find(stop)
-        if idx != -1:
-            text = text[:idx]
-    return text
-
-
-def _execute_code(problem: dict, completion: str, timeout: float = 3.0) -> bool:
-    """Run the completion against hidden tests in a subprocess."""
-
-    def _worker(queue, full_code):
-        try:
-            namespace = {}
-            exec(full_code, namespace)
-            check = namespace.get("check")
-            if check is None:
-                queue.put(False)
-                return
-            check(namespace.get(problem["entry_point"]))
-            queue.put(True)
-        except Exception:
-            queue.put(False)
-
-    full_code = problem["prompt"] + completion + "\n" + problem["test"]
-
-    queue: Queue = Queue()
-    proc = Process(target=_worker, args=(queue, full_code))
-    proc.start()
-    proc.join(timeout)
-
-    if proc.is_alive():
-        proc.terminate()
-        proc.join()
-        return False
-
-    try:
-        return queue.get_nowait()
-    except Exception:
-        return False
-
-
-def _pass_at_k(n: int, c: int, k: int) -> float:
-    """Unbiased estimator of pass@k."""
-    if n - c < k:
-        return 1.0
-    return 1.0 - float(prod(1.0 - k / np.arange(n - c + 1, n + 1)))
-
-
-def _deduplicate(completions: List[str]) -> List[str]:
+def deduplicate(seq: Sequence[str]) -> List[str]:
    seen = set()
-    unique = []
-    for c in completions:
-        if c not in seen:
-            seen.add(c)
-            unique.append(c)
-    return unique
+    return [x for x in seq if not (x in seen or seen.add(x))]


-def _generate(
+def generate_batch(
    engine: InferenceEngine,
    prompt: str,
-    num_samples: int,
+    n: int,
+    batch_size: int,
    max_tokens: int,
    temperature: float,
    top_p: float,
    top_k: int,
-    batch_size: int,
 ) -> List[str]:
-    batches = [prompt] * min(batch_size, num_samples)
    completions = []
-    remaining = num_samples
-
+    remaining = n
    while remaining > 0:
        current = min(batch_size, remaining)
-        batch_prompts = batches[:current]
        outputs = engine.generate(
-            prompt=batch_prompts,
+            prompt=[prompt] * current,
            stream=False,
            max_tokens=max_tokens,
            temperature=temperature,
            top_p=top_p,
            top_k=top_k,
        )
-        if isinstance(outputs, str):
-            outputs = [outputs]
-        completions.extend(outputs)
+        completions.extend(outputs if isinstance(outputs, list) else [outputs])
        remaining -= current
-
-    return _deduplicate(completions)
+    return deduplicate(completions)


-def evaluate(
+def extract_completions(
+    raw: Sequence[str],
+    entry_point: str,
+) -> List[str]:
+    bodies = []
+    for r in raw:
+        t = trim_stop(r)
+        body = extract_body(t, entry_point)
+        if body:
+            bodies.append(body)
+    return bodies
+
+
+def generate_all(
    engine: InferenceEngine,
-    problems: List[dict],
-    num_samples: int,
-    max_tokens: int,
-    temperature: float,
-    top_p: float,
-    top_k: int,
-    batch_size: int,
-    k_values: Tuple[int, ...] = (1, 10, 100),
-) -> Dict:
-    results = {}
-    all_pass_at_k = {k: [] for k in k_values}
-
-    for problem in tqdm.tqdm(problems, desc="HumanEval", unit="problem"):
-        task_id = problem["task_id"]
-        prompt = problem["prompt"]
-        entry_point = problem["entry_point"]
-
-        raw_completions = _generate(
+    problems: Sequence[dict],
+    cfg: EvalConfig,
+) -> List[dict]:
+    results = []
+    for problem in tqdm.tqdm(problems, desc="Generating", unit="problem"):
+        raw = generate_batch(
            engine,
-            prompt,
-            num_samples,
-            max_tokens,
-            temperature,
-            top_p,
-            top_k,
-            batch_size,
+            problem["prompt"],
+            cfg.num_samples,
+            cfg.batch_size,
+            cfg.max_tokens,
+            cfg.temperature,
+            cfg.top_p,
+            cfg.top_k,
+        )
+        bodies = extract_completions(raw, problem["entry_point"])
+        results.append(
+            dict(
+                task_id=problem["task_id"],
+                entry_point=problem["entry_point"],
+                prompt=problem["prompt"],
+                test=problem["test"],
+                completions=bodies,
+            )
        )
-
-        completions = []
-        for raw in raw_completions:
-            trimmed = _trim_stop_sequences(raw)
-            body = _extract_function_body(trimmed, entry_point)
-            if body:
-                completions.append(body)
-
-        passed = 0
-        for comp in completions:
-            if _execute_code(problem, comp):
-                passed += 1
-
-        n = len(completions)
-        c = passed
-        result = {"task_id": task_id, "n": n, "passed": c}
-        for k in k_values:
-            result[f"pass@{k}"] = round(_pass_at_k(n, c, k), 4)
-            all_pass_at_k[k].append(_pass_at_k(n, c, k))
-        results[task_id] = result
-
-    summary = {}
-    for k in k_values:
-        vals = all_pass_at_k[k]
-        summary[f"pass@{k}"] = round(float(np.mean(vals)), 4)
-    results["_summary"] = summary
-
    return results


-def main():
-    parser = argparse.ArgumentParser(description="HumanEval benchmark")
-    parser.add_argument(
-        "--param_path", type=str, default="./params", help="Model directory"
-    )
-    parser.add_argument(
-        "--data_path",
+def execute_one(args: tuple) -> bool:
+    full_code, entry_point, timeout = args
+    try:
+        r = subprocess.run(
+            [sys.executable, "-c", full_code],
+            capture_output=True,
+            timeout=timeout,
+        )
+        return r.returncode == 0
+    except subprocess.TimeoutExpired:
+        return False
+    except Exception:
+        return False
+
+
+def test_one(item: dict, cfg: EvalConfig) -> Tuple[str, int, int]:
+    from concurrent.futures import ProcessPoolExecutor
+
+    task_id = item["task_id"]
+    completions = item["completions"]
+    codes = [
+        (
+            item["prompt"] + c + "\n" + item["test"],
+            item["entry_point"],
+            cfg.test_timeout,
+        )
+        for c in completions
+    ]
+    n = len(codes)
+    passed = 0
+    with ProcessPoolExecutor(max_workers=cfg.test_workers) as pool:
+        for ok in pool.map(execute_one, codes):
+            if ok:
+                passed += 1
+    return task_id, n, passed
+
+
+def test_all(
+    items: Sequence[dict],
+    cfg: EvalConfig,
+) -> Iterator[Tuple[str, int, int]]:
+    for item in tqdm.tqdm(items, desc="Testing", unit="problem"):
+        yield test_one(item, cfg)
+
+
+def pass_at_k(n: int, c: int, k: int) -> float:
+    if n - c < k:
+        return 1.0
+    return 1.0 - float(prod(1.0 - k / np.arange(n - c + 1, n + 1)))
+
+
+def score_results(
+    results: Iterator[Tuple[str, int, int]],
+    k_values: Tuple[int, ...],
+) -> Dict:
+    # filter to k <= n (peek first result to get n)
+    first = next(results)
+    results = itertools.chain([first], results)
+    n = first[1]
+    k_values = tuple(k for k in k_values if k <= n)
+
+    scores = {k: [] for k in k_values}
+    output = {}
+    for task_id, n, passed in results:
+        entry = {"task_id": task_id, "n": n, "passed": passed}
+        for k in k_values:
+            pk = round(pass_at_k(n, passed, k), 4)
+            entry[f"pass@{k}"] = pk
+            scores[k].append(pk)
+        output[task_id] = entry
+
+    summary = {}
+    for k in k_values:
+        vals = scores[k]
+        summary[f"pass@{k}"] = round(float(np.mean(vals)), 4)
+    output["_summary"] = summary
+    return output
+
+
+def run_pipeline(cfg: EvalConfig) -> Dict:
+    if cfg.test_only:
+        with open(cfg.test_only, encoding="utf-8") as f:
+            generated = json.load(f)
+    else:
+        download(HUMANEVAL_URL, cfg.data_path)
+
+        problems = load_jsonl(cfg.data_path)
+        if cfg.problem_indices:
+            problems = [problems[i] for i in cfg.problem_indices if i < len(problems)]
+
+        engine = create_engine(cfg.param_path, cfg.batch_size)
+
+        try:
+            generated = generate_all(engine, problems, cfg)
+        finally:
+            engine.shutdown()
+
+        if cfg.output:
+            mid = cfg.output.replace(".json", "_completions.json")
+            save_json(mid, generated)
+            print(f"Completions saved to {mid}")
+
+        if cfg.generate_only:
+            return {}
+
+    results = test_all(generated, cfg)
+    scored = score_results(results, cfg.k_values)
+    return scored
+
+
+def parse_args(argv: Optional[List[str]] = None) -> EvalConfig:
+    p = argparse.ArgumentParser(description="HumanEval benchmark")
+    p.add_argument("--param_path", type=str, default="./params")
+    p.add_argument("--data_path", type=str, default="./humaneval/HumanEval.jsonl")
+    p.add_argument("--output", type=str, default=None)
+    p.add_argument(
+        "--test_only",
        type=str,
-        default="./humaneval/HumanEval.jsonl",
-        help="HumanEval JSONL file (auto-download if missing)",
-    )
-    parser.add_argument("--output", type=str, default=None, help="Output JSON path")
-    parser.add_argument(
-        "--num_samples",
-        type=int,
-        default=200,
-        help="Completions per problem",
-    )
-    parser.add_argument(
-        "--max_tokens", type=int, default=512, help="Max generation tokens"
-    )
-    parser.add_argument(
-        "--temperature", type=float, default=0.8, help="Sampling temperature"
-    )
-    parser.add_argument("--top_p", type=float, default=0.95, help="Top-p sampling")
-    parser.add_argument("--top_k", type=int, default=50, help="Top-k sampling")
-    parser.add_argument(
-        "--batch_size", type=int, default=1, help="Inference batch size"
-    )
-    parser.add_argument(
-        "--problems",
-        type=int,
-        nargs="+",
        default=None,
-        help="Specific problem indices (0-based)",
+        help="Skip generation, test existing completions JSON",
    )
-    args = parser.parse_args()
-
-    _download_humaneval(args.data_path)
-    problems = _load_problems(args.data_path)
-    if args.problems:
-        problems = [problems[i] for i in args.problems if i < len(problems)]
-
-    model = AutoModel.from_pretrained(args.param_path)
-    tokenizer = AutoTokenizer.from_pretrained(args.param_path)
-    model.to(device="cuda", dtype=torch.bfloat16)
-
-    engine = InferenceEngine(
-        model=model,
-        tokenizer=tokenizer,
-        max_batch_size=args.batch_size,
+    p.add_argument(
+        "--generate_only", action="store_true", help="Only generate, skip testing"
    )
+    p.add_argument("--num_samples", type=int, default=200)
+    p.add_argument("--max_tokens", type=int, default=512)
+    p.add_argument("--temperature", type=float, default=0.8)
+    p.add_argument("--top_p", type=float, default=0.95)
+    p.add_argument("--top_k", type=int, default=50)
+    p.add_argument("--batch_size", type=int, default=32)
+    p.add_argument("--test_workers", type=int, default=8)
+    p.add_argument("--test_timeout", type=float, default=3.0)
+    p.add_argument("--problems", type=int, nargs="+", default=None)
+    args = p.parse_args(argv)

-    results = evaluate(
-        engine=engine,
-        problems=problems,
+    return EvalConfig(
+        param_path=args.param_path,
+        data_path=args.data_path,
+        output=args.output,
+        test_only=args.test_only,
+        generate_only=args.generate_only,
        num_samples=args.num_samples,
        max_tokens=args.max_tokens,
        temperature=args.temperature,
        top_p=args.top_p,
        top_k=args.top_k,
        batch_size=args.batch_size,
-        k_values=(1, 10, 100),
+        test_workers=args.test_workers,
+        test_timeout=args.test_timeout,
+        problem_indices=args.problems,
    )

-    summary = results.pop("_summary")
+
+def report(scored: Dict):
+    summary = scored.pop("_summary", {})
    print(f"\n{'=' * 60}")
    for k, v in summary.items():
        print(f"  {k}: {v:.2%}")
    print(f"{'=' * 60}")
+    scored["_summary"] = summary

-    if args.output:
-        results["_summary"] = summary
-        with open(args.output, "w", encoding="utf-8") as f:
-            json.dump(results, f, indent=2, ensure_ascii=False)
-        print(f"Results saved to {args.output}")

-    engine.shutdown()
+def main():
+    cfg = parse_args()
+    scored = run_pipeline(cfg)
+    report(scored)
+    if cfg.output:
+        save_json(cfg.output, scored)
+        print(f"Results saved to {cfg.output}")


 if __name__ == "__main__":
@@ -1,31 +1,23 @@
 """IFD (Instruction Following Difficulty) data quality scoring.

-Computes IFD scores for instruction-response pairs to guide data selection.
-IFD = conditional_NLL / unconditional_NLL, where:
+IFD = conditional_NLL / unconditional_NLL

- conditional_NLL: average CE loss on response tokens given instruction context
- unconditional_NLL: average CE loss on response tokens alone
+- Messages format: plain text concatenation (no chat template)
+- Plain format: raw instr_key + resp_key fields

-Higher IFD (close to 1) = instruction provides less help = harder sample.
-Lower IFD (close to 0) = instruction provides strong guidance = easy sample.
-IFD > 1 = instruction misleads the model = likely low-quality data.
-
-Usage::
-
-    python scripts/eval/ifd.py --param_path ./params \
-        --input data.jsonl --output data_with_ifd.jsonl \
-        --instr_key instruction --resp_key response
-
-Disable chat template::
-
-    python scripts/eval/ifd.py --param_path ./params \
-        --input data.jsonl --output data_with_ifd.jsonl \
-        --instr_key instruction --resp_key response \
-        --no_chat_template
+v2 changelog:
+  - Same token set: unconditional pass prefixes resp with a plain-text sentinel
+    (default ``\\n``; use ``--sentinel_text ""`` for bos/pad fallback).
+    Both branches predict the identical N resp tokens.
+    Single-token answers (rl=1) are now supported.
+  - ctx_len tracked in output
+  - skip_reason for None samples (no more silent None)
+  - --per_token for per-token IFD breakdown
 """

 import argparse
 import json
+import statistics

 import torch
 import torch.nn.functional as F
@@ -35,216 +27,396 @@ from astrai.model import AutoModel
 from astrai.tokenize import AutoTokenizer


-def compute_ifd(
+def _pack_bins(pairs, max_len):
+    """BFD bin packing: pack (c+r) into bins of max total length."""
+    indexed = sorted(enumerate(pairs), key=lambda x: -(len(x[1][0]) + len(x[1][1])))
+    bins = []
+    lengths = []
+    for orig_idx, (c, r) in indexed:
+        size = len(c) + len(r)
+        best_bin = -1
+        for bi, rem in enumerate(lengths):
+            if rem >= size:
+                if best_bin < 0 or rem < lengths[best_bin]:
+                    best_bin = bi
+        if best_bin >= 0:
+            bins[best_bin].append((orig_idx, c, r))
+            lengths[best_bin] -= size
+        else:
+            bins.append([(orig_idx, c, r)])
+            lengths.append(max_len - size)
+    return bins
+
+
+def _resolve_sentinel_ids(tokenizer, sentinel_text):
+    """Tokenize the sentinel text for the unconditional pass prefix.
+
+    Falls back to bos/pad_token_id when sentinel_text is empty or
+    cannot be encoded.
+    """
+    if sentinel_text:
+        ids = tokenizer.encode(sentinel_text, add_special_tokens=False)
+        if ids:
+            return ids
+    for attr in ("bos_token_id", "pad_token_id", "eos_token_id"):
+        tid = getattr(tokenizer, attr, None)
+        if tid is not None:
+            return [tid]
+    return [0]
+
+
+@torch.inference_mode()
+def _score_batch(
+    pairs, model, device, max_len=2048, sentinel_ids=None, per_token=False
+):
+    """BFD-packed IFD with text-sentinel-anchored unconditional pass.
+
+    Conditional:   (ctx + resp[0..i-1]) → resp[i],  i = 0..N-1
+    Unconditional: (<sentinel> + resp[0..i-1]) → resp[i],  i = 0..N-1
+
+    Both branches predict the identical N response tokens.  A short
+    plain-text sentinel gives the unconditional pass a prefix so that
+    every response token can be predicted.  Single-token answers (rl=1)
+    are supported.
+    """
+    if not pairs:
+        return []
+
+    if sentinel_ids is None:
+        sentinel_ids = [0]
+
+    bins = _pack_bins(pairs, max_len)
+    result = [None] * len(pairs)
+
+    # ---- conditional pass (packed, per-document position IDs) ----
+    for bin_items in bins:
+        seq_ids = []
+        global_pos = []
+        doc_ids = []
+        doc_offsets = []
+
+        for di, (orig_idx, c, r) in enumerate(bin_items):
+            ctx_len = len(c)
+            start = len(seq_ids)
+            item_len = len(c) + len(r)
+            seq_ids.extend(c)
+            seq_ids.extend(r)
+            end = len(seq_ids)
+            global_pos.extend(range(item_len))
+            doc_ids.extend([di] * item_len)
+            doc_offsets.append((start, end, orig_idx, ctx_len))
+
+        full_ids = torch.tensor([seq_ids], device=device, dtype=torch.long)
+        pos_ids = torch.tensor([global_pos], device=device, dtype=torch.long)
+        seq_len = len(seq_ids)
+        causal = torch.tril(
+            torch.ones(seq_len, seq_len, dtype=torch.bool, device=device)
+        )
+        doc_t = torch.tensor([doc_ids], device=device)
+        doc_mask = doc_t.unsqueeze(-1) == doc_t.unsqueeze(-2)
+        attn_mask = (causal & doc_mask[0]).unsqueeze(0).unsqueeze(0)
+        logits_full = model(full_ids, position_ids=pos_ids, input_mask=attn_mask)[
+            "logits"
+        ][0]
+
+        for start, end, orig_idx, ctx_len in doc_offsets:
+            rl = end - start - ctx_len
+            resp_start = start + ctx_len - 1
+            resp_logits = logits_full[resp_start : end - 1]
+            resp_targets = torch.tensor(
+                seq_ids[start + ctx_len : end], device=device, dtype=torch.long
+            )
+            cond_losses = F.cross_entropy(
+                resp_logits, resp_targets, reduction="none"
+            ).cpu()
+            result[orig_idx] = {
+                "_cond_losses": cond_losses,
+                "_rl": rl,
+                "_ctx_len": ctx_len,
+            }
+
+    # ---- unconditional pass (sentinel-prefixed, batched 2D) ----
+    valid_items = [
+        (
+            i,
+            result[i]["_rl"],
+            result[i]["_ctx_len"],
+            result[i]["_cond_losses"],
+            pairs[i][1],
+        )
+        for i in range(len(pairs))
+        if result[i] is not None and "_cond_losses" in result[i]
+    ]
+    if not valid_items:
+        return result
+
+    valid_items.sort(key=lambda x: -x[1])
+    prefix_len = len(sentinel_ids)
+    max_rl = prefix_len + max(rl for _, rl, _, _, _ in valid_items)
+    bsz = len(valid_items)
+
+    u_batch = torch.zeros(bsz, max_rl, dtype=torch.long, device=device)
+    for ri, (_, rl, _, _, r_ids) in enumerate(valid_items):
+        u_batch[ri, :prefix_len] = torch.tensor(sentinel_ids, dtype=torch.long)
+        u_batch[ri, prefix_len : prefix_len + rl] = torch.tensor(
+            r_ids, dtype=torch.long
+        )
+
+    logits_resp = model(u_batch)["logits"]
+
+    for ri, (orig_idx, rl, ctx_len, cond_losses, _) in enumerate(valid_items):
+        unp_logits = logits_resp[ri, prefix_len - 1 : prefix_len - 1 + rl]
+        unp_targets = u_batch[ri, prefix_len : prefix_len + rl]
+        uncond_losses = F.cross_entropy(unp_logits, unp_targets, reduction="none").cpu()
+
+        L_cond = cond_losses.mean().item()
+        L_uncond = uncond_losses.mean().item()
+        ifd = L_cond / L_uncond if L_uncond > 0 else None
+
+        out = {
+            "L_cond": round(L_cond, 6),
+            "L_uncond": round(L_uncond, 6),
+            "ifd": round(ifd, 6) if ifd is not None else None,
+            "ctx_len": ctx_len,
+            "resp_len": rl,
+        }
+        if per_token:
+            per = [
+                (round(c.item() / u.item(), 6) if u.item() > 0 else None)
+                for c, u in zip(cond_losses, uncond_losses)
+            ]
+            out["ifd_per_token"] = per
+        result[orig_idx] = out
+
+    return result
+
+
+def _trim(context_ids, resp_ids, max_len):
+    """Truncate to fit max_len, keeping response intact if possible."""
+    if len(resp_ids) > max_len // 2:
+        resp_ids = resp_ids[: max_len // 2]
+    full_ids = context_ids + resp_ids
+    if len(full_ids) <= max_len:
+        return context_ids, resp_ids
+    overflow = len(full_ids) - max_len
+    if overflow >= len(context_ids):
+        return [], resp_ids[:max_len]
+    return context_ids[overflow:], resp_ids
+
+
+def score_plain(
    model,
    tokenizer,
-    instruction: str,
-    response: str,
-    device: str,
-    max_len: int = 2048,
-    use_chat_template: bool = False,
-) -> dict:
-    if use_chat_template:
-        return _compute_ifd_with_template(
-            model, tokenizer, instruction, response, device, max_len
-        )
-    return _compute_ifd_raw(model, tokenizer, instruction, response, device, max_len)
-
-
-def _compute_ifd_raw(model, tokenizer, instruction, response, device, max_len) -> dict:
-    instr_ids = tokenizer.encode(instruction)
-    resp_ids = tokenizer.encode(response)
-
-    if not resp_ids:
+    instruction,
+    response,
+    device,
+    max_len=2048,
+    sentinel_ids=None,
+    per_token=False,
+):
+    """Compute IFD for a single instruction-response pair (plain format)."""
+    ctx_ids = tokenizer.encode(instruction, add_special_tokens=False)
+    resp_ids = tokenizer.encode(response, add_special_tokens=False)
+    ctx_ids, resp_ids = _trim(ctx_ids, resp_ids, max_len)
+    if not ctx_ids or not resp_ids:
        return {
            "L_cond": None,
            "L_uncond": None,
            "ifd": None,
-            "error": "empty response",
+            "skip_reason": "empty ctx or resp",
        }
-
-    qa_len = len(instr_ids) + len(resp_ids)
-    if qa_len > max_len:
-        overflow = qa_len - max_len
-        instr_ids = instr_ids[overflow:]
-
-    instr_len = len(instr_ids)
-    resp_len = len(resp_ids)
-
-    qa_ids = instr_ids + resp_ids
-    qa_tensor = torch.tensor([qa_ids], device=device, dtype=torch.long)
-
-    with torch.inference_mode():
-        logits_qa = model(qa_tensor)["logits"][0]
-
-    resp_logits = logits_qa[instr_len - 1 : -1]
-    resp_targets = torch.tensor(resp_ids, device=device, dtype=torch.long)
-    L_cond = F.cross_entropy(resp_logits, resp_targets, reduction="mean").item()
-
-    resp_tensor = torch.tensor([resp_ids], device=device, dtype=torch.long)
-
-    with torch.inference_mode():
-        logits_resp = model(resp_tensor)["logits"][0]
-
-    unp_logits = logits_resp[:-1]
-    unp_targets = resp_tensor[0, 1:]
-    L_uncond = F.cross_entropy(unp_logits, unp_targets, reduction="mean").item()
-
-    ifd = L_cond / L_uncond if L_uncond > 0 else None
-
-    return {
-        "L_cond": round(L_cond, 6),
-        "L_uncond": round(L_uncond, 6),
-        "ifd": round(ifd, 6) if ifd is not None else None,
-        "instr_len": instr_len,
-        "resp_len": resp_len,
-        "error": None,
-    }
+    return _score_batch(
+        [(ctx_ids, resp_ids)],
+        model,
+        device,
+        max_len,
+        sentinel_ids=sentinel_ids,
+        per_token=per_token,
+    )[0]


-def _compute_ifd_with_template(
-    model, tokenizer, instruction, response, device, max_len
-) -> dict:
-    instr_prefix = tokenizer.apply_chat_template(
-        [{"role": "user", "content": instruction}],
-        tokenize=False,
-        add_generation_prompt=True,
+def score_messages(
+    model, tokenizer, messages, device, max_len=2048, sentinel_ids=None, per_token=False
+):
+    """Compute IFD for each assistant turn in a messages array."""
+    turns = []
+    for i, msg in enumerate(messages):
+        if msg.get("role") != "assistant":
+            continue
+        ctx_text = "\n\n".join(m["content"] for m in messages[:i])
+        ctx_ids = tokenizer.encode(ctx_text)
+        resp_ids = tokenizer.encode(msg["content"], add_special_tokens=False)
+        ctx_ids, resp_ids = _trim(ctx_ids, resp_ids, max_len)
+        if ctx_ids and resp_ids:
+            turns.append((ctx_ids, resp_ids))
+    if not turns:
+        return None
+    raw_scores = _score_batch(
+        turns, model, device, max_len, sentinel_ids=sentinel_ids, per_token=per_token
    )
-    full_text = tokenizer.apply_chat_template(
-        [
-            {"role": "user", "content": instruction},
-            {"role": "assistant", "content": response},
-        ],
-        tokenize=False,
-        add_generation_prompt=False,
-    )
-
-    full_ids = tokenizer.encode(full_text)
-    prefix_ids = tokenizer.encode(instr_prefix)
-    resp_ids = tokenizer.encode(response)
-
-    if not resp_ids:
-        return {
-            "L_cond": None,
-            "L_uncond": None,
-            "ifd": None,
-            "error": "empty response",
-        }
-
-    if len(full_ids) > max_len:
-        overflow = len(full_ids) - max_len
-        full_ids = full_ids[overflow:]
-        prefix_len = len(prefix_ids) - overflow
-        prefix_len = max(0, prefix_len)
-    else:
-        prefix_len = len(prefix_ids)
-
-    cond_tensor = torch.tensor([full_ids], device=device, dtype=torch.long)
-
-    with torch.inference_mode():
-        logits_qa = model(cond_tensor)["logits"][0]
-
-    resp_start = prefix_len - 1
-    resp_end = len(full_ids) - 1
-    if resp_end <= resp_start:
-        return {
-            "L_cond": None,
-            "L_uncond": None,
-            "ifd": None,
-            "error": "response truncated entirely",
-        }
-
-    resp_logits = logits_qa[resp_start:resp_end]
-    resp_targets = torch.tensor(full_ids[prefix_len:], device=device, dtype=torch.long)
-    L_cond = F.cross_entropy(resp_logits, resp_targets, reduction="mean").item()
-
-    resp_tensor = torch.tensor([resp_ids], device=device, dtype=torch.long)
-
-    with torch.inference_mode():
-        logits_resp = model(resp_tensor)["logits"][0]
-
-    unp_logits = logits_resp[:-1]
-    unp_targets = resp_tensor[0, 1:]
-    L_uncond = F.cross_entropy(unp_logits, unp_targets, reduction="mean").item()
-
-    ifd = L_cond / L_uncond if L_uncond > 0 else None
-
+    valid = [s for s in raw_scores if s is not None and s.get("ifd") is not None]
+    if not valid:
+        return {"ifd": None, "ifd_turns": raw_scores}
+    avg = sum(s["ifd"] for s in valid) / len(valid)
    return {
-        "L_cond": round(L_cond, 6),
-        "L_uncond": round(L_uncond, 6),
-        "ifd": round(ifd, 6) if ifd is not None else None,
-        "instr_len": prefix_len,
-        "resp_len": len(resp_ids),
-        "error": None,
+        "ifd": avg,
+        "ifd_detail": valid[0] if len(valid) == 1 else None,
+        "ifd_turns": raw_scores,
    }


 def process_file(
-    param_path: str,
-    input_file: str,
-    output_file: str,
-    instr_key: str,
-    resp_key: str,
-    max_len: int,
-    use_chat_template: bool = False,
+    param_path,
+    input_file,
+    output_file,
+    instr_key,
+    resp_key,
+    max_len=2048,
+    data_format="plain",
+    batch_size=1,
+    device=None,
+    sentinel_text="\n",
+    per_token=False,
 ):
-    device = "cuda" if torch.cuda.is_available() else "cpu"
-    dtype = torch.bfloat16 if device == "cuda" else torch.float32
+    if device is None:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+    dtype = torch.bfloat16 if "cuda" in device else torch.float32

    model = AutoModel.from_pretrained(param_path)
    tokenizer = AutoTokenizer.from_pretrained(param_path)
    model.to(device=device, dtype=dtype)
    model.eval()

-    if use_chat_template and tokenizer._chat_template is None:
-        raise RuntimeError(
-            "--use_chat_template specified but tokenizer has no chat template. "
-            "Add a chat_template to tokenizer_config.json or omit the flag."
-        )
+    sentinel_ids = _resolve_sentinel_ids(tokenizer, sentinel_text)

-    with open(input_file, "r", encoding="utf-8") as f:
+    with open(input_file, encoding="utf-8") as f:
        data = [json.loads(line) for line in f if line.strip()]

    results = []
-    ifd_values = []
+    all_ifds = []
+    buffer = []

-    with torch.inference_mode():
-        for item in tqdm.tqdm(data, desc="Computing IFD", unit="sample"):
-            instruction = item[instr_key]
-            response = item[resp_key]
-            scores = compute_ifd(
+    for item in tqdm.tqdm(data, desc="Computing IFD", unit="sample"):
+        if data_format == "messages":
+            turns = []
+            for i, msg in enumerate(item.get("messages", [])):
+                if msg.get("role") != "assistant":
+                    continue
+                ctx_text = "\n\n".join(m["content"] for m in item["messages"][:i])
+                ctx_ids = tokenizer.encode(ctx_text)
+                resp_ids = tokenizer.encode(msg["content"], add_special_tokens=False)
+                ctx_ids, resp_ids = _trim(ctx_ids, resp_ids, max_len)
+                if ctx_ids and resp_ids:
+                    turns.append((ctx_ids, resp_ids))
+            if not turns:
+                results.append(
+                    {
+                        **item,
+                        "ifd": None,
+                        "skip_reason": "no valid assistant turns",
+                        "ifd_turns": [],
+                    }
+                )
+                continue
+            buffer.append((item, turns, "messages"))
+        else:
+            ctx_ids = tokenizer.encode(item[instr_key], add_special_tokens=False)
+            resp_ids = tokenizer.encode(item[resp_key], add_special_tokens=False)
+            ctx_ids, resp_ids = _trim(ctx_ids, resp_ids, max_len)
+            if not ctx_ids or not resp_ids:
+                results.append(
+                    {
+                        **item,
+                        "ifd": None,
+                        "ifd_detail": {"skip_reason": "empty ctx or resp"},
+                    }
+                )
+                continue
+            buffer.append((item, [(ctx_ids, resp_ids)], "plain"))
+
+        if len(buffer) >= batch_size:
+            _flush_buffer(
+                buffer,
+                results,
+                all_ifds,
                model,
-                tokenizer,
-                instruction,
-                response,
                device,
                max_len,
-                use_chat_template=use_chat_template,
+                sentinel_ids,
+                per_token,
            )
-            ifd_values.append(scores["ifd"])
-            results.append({**item, "ifd": scores["ifd"], "ifd_detail": scores})
+
+    if buffer:
+        _flush_buffer(
+            buffer, results, all_ifds, model, device, max_len, sentinel_ids, per_token
+        )

    with open(output_file, "w", encoding="utf-8") as f:
        for item in results:
            f.write(json.dumps(item, ensure_ascii=False) + "\n")

-    valid_ifd = [v for v in ifd_values if v is not None]
+    valid_ifd = [v for v in all_ifds if v is not None]
    if valid_ifd:
-        import statistics
-
        print(f"\n{'=' * 50}")
-        print(f"  Samples:    {len(data)}")
-        print(f"  Valid IFD:  {len(valid_ifd)}")
-        print(f"  Mean IFD:   {statistics.mean(valid_ifd):.4f}")
-        print(f"  Median IFD: {statistics.median(valid_ifd):.4f}")
-        print(f"  Stdev IFD:  {statistics.stdev(valid_ifd):.4f}")
-        print(f"  Min IFD:    {min(valid_ifd):.4f}")
-        print(f"  Max IFD:    {max(valid_ifd):.4f}")
+        print(f"  Samples:       {len(data)}")
+        print(f"  Valid IFD:     {len(valid_ifd)}")
+        print(f"  Skipped:       {len(data) - len(valid_ifd)}")
+        print(f"  Mean IFD:      {statistics.mean(valid_ifd):.4f}")
+        print(f"  Median IFD:    {statistics.median(valid_ifd):.4f}")
+        if len(valid_ifd) > 1:
+            print(f"  Stdev IFD:     {statistics.stdev(valid_ifd):.4f}")
+        print(f"  Min IFD:       {min(valid_ifd):.4f}")
+        print(f"  Max IFD:       {max(valid_ifd):.4f}")
        print(f"{'=' * 50}")
-
    print(f"Results saved to {output_file}")


+def _flush_buffer(
+    buffer, results, all_ifds, model, device, max_len, sentinel_ids, per_token
+):
+    all_pairs = []
+    indices = []
+    for item, turns, fmt in buffer:
+        start = len(all_pairs)
+        all_pairs.extend(turns)
+        indices.append((item, turns, fmt, start, len(all_pairs)))
+
+    raw = _score_batch(
+        all_pairs,
+        model,
+        device,
+        max_len,
+        sentinel_ids=sentinel_ids,
+        per_token=per_token,
+    )
+
+    for item, turns, fmt, start, end in indices:
+        turn_scores = raw[start:end]
+        if fmt == "messages":
+            valid = [
+                s for s in turn_scores if s is not None and s.get("ifd") is not None
+            ]
+            if not valid:
+                results.append({**item, "ifd": None, "ifd_turns": turn_scores})
+            else:
+                avg = sum(s["ifd"] for s in valid) / len(valid)
+                all_ifds.append(avg)
+                results.append(
+                    {
+                        **item,
+                        "ifd": avg,
+                        "ifd_detail": valid[0] if len(valid) == 1 else None,
+                        "ifd_turns": turn_scores,
+                    }
+                )
+        else:
+            score = turn_scores[0]
+            all_ifds.append(score.get("ifd"))
+            results.append({**item, "ifd": score.get("ifd"), "ifd_detail": score})
+
+    buffer.clear()
+
+
 def main():
    parser = argparse.ArgumentParser(
        description="Compute IFD scores for instruction-response data"
@@ -252,29 +424,34 @@ def main():
    parser.add_argument("--param_path", type=str, required=True, help="Model directory")
    parser.add_argument("--input", type=str, required=True, help="Input JSONL file")
    parser.add_argument("--output", type=str, required=True, help="Output JSONL file")
+    parser.add_argument("--max_len", type=int, default=2048, help="Max token length")
    parser.add_argument(
-        "--instr_key",
+        "--format",
        type=str,
-        default="instruction",
-        help="Key for instruction field",
+        default="plain",
+        choices=["plain", "messages"],
+        help="Input format",
    )
    parser.add_argument(
-        "--resp_key",
+        "--instr_key", type=str, default="instruction", help="Key for instruction field"
+    )
+    parser.add_argument(
+        "--resp_key", type=str, default="response", help="Key for response field"
+    )
+    parser.add_argument(
+        "--batch_size", type=int, default=8, help="Batch size for model forward passes"
+    )
+    parser.add_argument("--device", type=str, default=None, help="Device (e.g. cuda:0)")
+    parser.add_argument(
+        "--sentinel_text",
        type=str,
-        default="response",
-        help="Key for response field",
+        default="\n",
+        help='Plain-text prefix for unconditional pass (default: "\\n"). Use "" for bos/pad fallback.',
    )
    parser.add_argument(
-        "--max_len",
-        type=int,
-        default=2048,
-        help="Max token length (instruction truncated to fit)",
-    )
-    parser.add_argument(
-        "--no_chat_template",
+        "--per_token",
        action="store_true",
-        default=False,
-        help="Disable chat template, use raw text concatenation",
+        help="Include per-token IFD breakdown in output",
    )
    args = parser.parse_args()

@@ -285,7 +462,11 @@ def main():
        args.instr_key,
        args.resp_key,
        args.max_len,
-        use_chat_template=not args.no_chat_template,
+        data_format=args.format,
+        batch_size=args.batch_size,
+        device=args.device,
+        sentinel_text=args.sentinel_text,
+        per_token=args.per_token,
    )


@@ -0,0 +1,153 @@
+"""ROUGE evaluation (manual implementation, no external deps).
+
+Computes ROUGE-1, ROUGE-2, ROUGE-L precision, recall, and F1.
+
+Usage::
+
+    # Batch evaluation from JSONL (each line: {"reference": ..., "candidate": ...})
+    python scripts/eval/evaluate_rouge.py --data_path preds.jsonl --output results.json
+
+    # As a library
+    from scripts.eval.evaluate_rouge import compute_rouge
+    scores = compute_rouge("the cat sat on the mat", "the cat sat")
+"""
+
+import argparse
+import json
+from collections import Counter
+from typing import Dict, List, Tuple
+
+
+def _tokenize(text: str) -> List[str]:
+    return text.split()
+
+
+def _ngrams(tokens: List[str], n: int) -> Counter:
+    return Counter(zip(*[tokens[i:] for i in range(n)]))
+
+
+def _lcs(x: List[str], y: List[str]) -> int:
+    m, n = len(x), len(y)
+    dp = [[0] * (n + 1) for _ in range(m + 1)]
+    for i in range(1, m + 1):
+        xi = x[i - 1]
+        dpi = dp[i]
+        dpi_1 = dp[i - 1]
+        for j in range(1, n + 1):
+            if xi == y[j - 1]:
+                dpi[j] = dpi_1[j - 1] + 1
+            else:
+                dpi[j] = dpi_1[j] if dpi_1[j] > dpi[j - 1] else dpi[j - 1]
+    return dp[m][n]
+
+
+def _f1(precision: float, recall: float) -> float:
+    if precision + recall == 0:
+        return 0.0
+    return 2 * precision * recall / (precision + recall)
+
+
+def _rouge_n(ref_tokens: List[str], cand_tokens: List[str], n: int) -> Dict[str, float]:
+    ref_ngrams = _ngrams(ref_tokens, n)
+    cand_ngrams = _ngrams(cand_tokens, n)
+
+    overlap = sum((cand_ngrams & ref_ngrams).values())
+    cand_total = sum(cand_ngrams.values())
+    ref_total = sum(ref_ngrams.values())
+
+    precision = overlap / cand_total if cand_total > 0 else 0.0
+    recall = overlap / ref_total if ref_total > 0 else 0.0
+    f1 = _f1(precision, recall)
+
+    return {"precision": precision, "recall": recall, "f1": f1}
+
+
+def _rouge_l(ref_tokens: List[str], cand_tokens: List[str]) -> Dict[str, float]:
+    lcs_len = _lcs(ref_tokens, cand_tokens)
+    ref_len = len(ref_tokens)
+    cand_len = len(cand_tokens)
+
+    recall = lcs_len / ref_len if ref_len > 0 else 0.0
+    precision = lcs_len / cand_len if cand_len > 0 else 0.0
+    f1 = _f1(precision, recall)
+
+    return {"precision": precision, "recall": recall, "f1": f1}
+
+
+def compute_rouge(
+    reference: str, candidate: str, n: int = 2
+) -> Dict[str, Dict[str, float]]:
+    """Compute ROUGE-N (1..n) and ROUGE-L scores.
+
+    Returns::
+
+        {
+            "rouge-1": {"precision": ..., "recall": ..., "f1": ...},
+            "rouge-2": {"precision": ..., "recall": ..., "f1": ...},
+            "rouge-l": {"precision": ..., "recall": ..., "f1": ...},
+        }
+    """
+    ref_tokens = _tokenize(reference)
+    cand_tokens = _tokenize(candidate)
+
+    results = {}
+    for i in range(1, n + 1):
+        results[f"rouge-{i}"] = _rouge_n(ref_tokens, cand_tokens, i)
+    results["rouge-l"] = _rouge_l(ref_tokens, cand_tokens)
+    return results
+
+
+def evaluate_file(data_path: str) -> Dict:
+    with open(data_path, "r", encoding="utf-8") as f:
+        pairs = [json.loads(line) for line in f if line.strip()]
+
+    agg = {
+        k: {"precision": 0.0, "recall": 0.0, "f1": 0.0}
+        for k in ("rouge-1", "rouge-2", "rouge-l")
+    }
+    per_item = []
+
+    for item in pairs:
+        ref = item["reference"]
+        cand = item["candidate"]
+        scores = compute_rouge(ref, cand)
+        per_item.append({**item, "scores": scores})
+        for k, v in scores.items():
+            agg[k]["precision"] += v["precision"]
+            agg[k]["recall"] += v["recall"]
+            agg[k]["f1"] += v["f1"]
+
+    n = len(pairs)
+    for k in agg:
+        agg[k] = {m: v / n for m, v in agg[k].items()}
+
+    return {"num_samples": n, "aggregate": agg, "per_item": per_item}
+
+
+def main():
+    parser = argparse.ArgumentParser(description="ROUGE evaluation")
+    parser.add_argument(
+        "--data_path", required=True, help="JSONL with reference/candidate per line"
+    )
+    parser.add_argument("--output", type=str, default=None, help="Output JSON path")
+    args = parser.parse_args()
+
+    results = evaluate_file(args.data_path)
+    agg = results["aggregate"]
+
+    print(f"Samples: {results['num_samples']}")
+    print()
+    for metric in ("rouge-1", "rouge-2", "rouge-l"):
+        s = agg[metric]
+        print(
+            f"  {metric:8s}  P={s['precision']:.4f}  R={s['recall']:.4f}  F1={s['f1']:.4f}"
+        )
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            json.dump(results, f, indent=2, ensure_ascii=False)
+        print(f"\nSaved to {args.output}")
+
+
+if __name__ == "__main__":
+    main()
@@ -150,8 +150,8 @@ def parse_args() -> argparse.Namespace:
    parser.add_argument(
        "--metrics",
        nargs="*",
-        default=["loss", "lr"],
-        help="Metrics to log (e.g. --metrics loss lr val_loss). Default: loss lr.",
+        default=["loss", "lr", "grad_norm"],
+        help="Metrics to log (e.g. --metrics loss lr val_loss). Default: loss lr grad_norm.",
    )
    parser.add_argument(
        "--log_dir",
@@ -159,12 +159,6 @@ def parse_args() -> argparse.Namespace:
        default="checkpoint/logs",
        help="Directory for metric logs.",
    )
-    parser.add_argument(
-        "--log_interval",
-        type=int,
-        default=100,
-        help="Number of batch iterations between metric logs.",
-    )
    parser.add_argument(
        "--grpo_sync_interval",
        type=int,
@@ -175,7 +169,10 @@ def parse_args() -> argparse.Namespace:
        "--start_epoch", type=int, default=0, help="Start epoch for training."
    )
    parser.add_argument(
-        "--start_batch", type=int, default=0, help="Start batch for training."
+        "--start_samples",
+        type=int,
+        default=0,
+        help="Start samples (per rank) for training.",
    )

    parser.add_argument(
@@ -269,7 +266,20 @@ def create_model(config):


 def create_optimizer(model, **kwargs) -> optim.Optimizer:
-    return optim.AdamW(model.parameters(), fused=True, **kwargs)
+    decay_params = []
+    no_decay_params = []
+    for name, param in model.named_parameters():
+        if not param.requires_grad:
+            continue
+        if param.dim() < 2 or "norm" in name or "bias" in name:
+            no_decay_params.append(param)
+        else:
+            decay_params.append(param)
+    param_groups = [
+        {"params": decay_params, "weight_decay": kwargs.pop("weight_decay", 0.01)},
+        {"params": no_decay_params, "weight_decay": 0.0},
+    ]
+    return optim.AdamW(param_groups, fused=True, **kwargs)


 def create_scheduler(
@@ -304,7 +314,7 @@ def train(
    n_epoch: int,
    batch_per_device: int,
    start_epoch: int,
-    start_batch: int,
+    start_samples: int,
    grad_accum_steps: int,
    warmup_ratio: float,
    ckpt_interval: int,
@@ -313,7 +323,6 @@ def train(
    val_step: int,
    metrics: list[str],
    log_dir: str,
-    log_interval: int,
    dpo_beta: float,
    grpo_clip_eps: float,
    grpo_kl_coef: float,
@@ -431,7 +440,7 @@ def train(
        n_epoch=n_epoch,
        batch_per_device=batch_per_device,
        start_epoch=start_epoch,
-        start_batch=start_batch,
+        start_samples=start_samples,
        ckpt_interval=ckpt_interval,
        grad_accum_steps=grad_accum_steps,
        max_grad_norm=max_grad_norm,
@@ -449,7 +458,6 @@ def train(
        val_step=val_step,
        metrics=metrics,
        log_dir=log_dir,
-        log_interval=log_interval,
        gradient_checkpointing_modules=grad_ckpt_modules,
        executor_kwargs=executor_kwargs,
        extra_kwargs=strategy_kwargs,
@@ -75,7 +75,7 @@ class MultiTurnDataset(Dataset):


 class EarlyStoppingDataset(Dataset):
-    """Dataset that triggers early stopping after a specified number of iterations."""
+    """Dataset that triggers early stopping after consuming a specified number of samples."""

    def __init__(self, length=10, stop_after=5):
        self.length = length
@@ -25,7 +25,9 @@ def test_single_process():

        scheduler.step()

-    checkpoint = Checkpoint(state_dict=model.state_dict(), epoch=3, iteration=30)
+    checkpoint = Checkpoint(
+        state_dict=model.state_dict(), epoch=3, consumed_samples=120
+    )

    with tempfile.TemporaryDirectory() as tmpdir:
        checkpoint.save(tmpdir)
@@ -33,7 +35,7 @@ def test_single_process():
        loaded_checkpoint = Checkpoint.load(tmpdir)

        assert loaded_checkpoint.epoch == 3
-        assert loaded_checkpoint.iteration == 30
+        assert loaded_checkpoint.consumed_samples == 120


 def test_checkpoint_with_extra():
@@ -46,7 +48,10 @@ def test_checkpoint_with_extra():
        "scheduler": {"last_epoch": 5},
    }
    checkpoint = Checkpoint(
-        state_dict=model.state_dict(), epoch=1, iteration=10, extra=extra
+        state_dict=model.state_dict(),
+        epoch=1,
+        consumed_samples=40,
+        extra=extra,
    )

    with tempfile.TemporaryDirectory() as tmpdir:
@@ -77,7 +82,7 @@ def simple_training():
    checkpoint = Checkpoint(
        state_dict=model.state_dict(),
        epoch=2,
-        iteration=10,
+        consumed_samples=40,
    )

    rank = get_rank()
@@ -1,14 +1,18 @@
+import json
 import os

 import numpy as np
 import pytest
 import torch

+from astrai.config.preprocess_config import PipelineConfig
 from astrai.dataset.dataset import DatasetFactory, SEQDataset
 from astrai.dataset.storage import (
    H5Store,
    StoreFactory,
    detect_format,
+)
+from astrai.serialization import (
    load_bin,
    save_bin,
    save_h5,
@@ -19,6 +23,39 @@ def _rand_seq(length, vocab=1000):
    return torch.randint(0, vocab, (length,), dtype=torch.int64)


+def _save_test_tokenizer(test_dir, tokenizer):
+    tokenizer_path = os.path.join(test_dir, "tokenizer")
+    os.makedirs(tokenizer_path, exist_ok=True)
+    tokenizer.save_pretrained(tokenizer_path)
+    return tokenizer_path
+
+
+def _write_jsonl_dataset(test_dir, tokenizer_path, records, config_overrides=None):
+    data_dir = os.path.join(test_dir, "jsonl_data")
+    os.makedirs(data_dir, exist_ok=True)
+
+    with open(os.path.join(data_dir, "data.jsonl"), "w", encoding="utf-8") as f:
+        for record in records:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+    config = {
+        "tokenizer_path": tokenizer_path,
+        "version": 1,
+        "input": {"sections": [{"field": "text", "action": "train"}]},
+        "preprocessing": {"max_seq_len": 128},
+        "output": {"position_ids_mode": "continuous"},
+    }
+    if config_overrides:
+        config.update(config_overrides)
+
+    with open(
+        os.path.join(data_dir, "dataset_config.json"), "w", encoding="utf-8"
+    ) as f:
+        json.dump(config, f, ensure_ascii=False, indent=2)
+
+    return data_dir
+
+
 def _make_seq_dataset(
    test_dir, name="data", seq_length=200, train_type="seq", data=None, **load_kwargs
 ):
@@ -372,3 +409,106 @@ def test_dataset_load_explicit_storage_type(base_test_env):
    dataset = _make_seq_dataset(test_dir, "explicit", storage_type="h5")
    assert len(dataset) > 0
    assert dataset.count == 200
+
+
+def test_detect_format_jsonl_dir(base_test_env):
+    test_dir = base_test_env["test_dir"]
+    tokenizer_path = _save_test_tokenizer(test_dir, base_test_env["tokenizer"])
+    data_dir = _write_jsonl_dataset(
+        test_dir,
+        tokenizer_path,
+        [{"text": "hello world"}, {"text": "foo bar baz"}],
+    )
+    assert detect_format(data_dir) == "jsonl"
+
+
+def test_jsonl_store_seq(base_test_env):
+    test_dir = base_test_env["test_dir"]
+    tokenizer_path = _save_test_tokenizer(test_dir, base_test_env["tokenizer"])
+    data_dir = _write_jsonl_dataset(
+        test_dir,
+        tokenizer_path,
+        [{"text": "hello world"}, {"text": "foo bar baz qux"}],
+        config_overrides={"preprocessing": {"max_seq_len": 128, "min_chars": 0}},
+    )
+
+    store = StoreFactory.create("jsonl")
+    store.load(data_dir)
+    assert len(store) > 0
+    assert "sequence" in store.keys
+
+    dataset = DatasetFactory.load("seq", data_dir, window_size=8)
+    assert len(dataset) > 0
+    item = dataset[0]
+    assert "input_ids" in item
+    assert "target_ids" in item
+    assert item["input_ids"].dtype == torch.long
+
+
+def test_jsonl_store_sft(base_test_env):
+    test_dir = base_test_env["test_dir"]
+    tokenizer = base_test_env["tokenizer"]
+    tokenizer.set_chat_template(
+        "{% for message in messages %}{{ message['role'] }}:{{ message['content'] }}\n{% endfor %}"
+    )
+    tokenizer_path = _save_test_tokenizer(test_dir, tokenizer)
+    data_dir = _write_jsonl_dataset(
+        test_dir,
+        tokenizer_path,
+        [
+            {
+                "messages": [
+                    {"role": "system", "content": "sys"},
+                    {"role": "user", "content": "hi"},
+                    {"role": "assistant", "content": "hello"},
+                ]
+            }
+        ],
+        config_overrides={
+            "input": {
+                "sections": [{"field": "messages", "action": "$role", "template": True}]
+            },
+            "mask": {"system": "mask", "user": "mask", "assistant": "train"},
+            "mask_default": "mask",
+        },
+    )
+
+    store = StoreFactory.create("jsonl")
+    store.load(data_dir)
+    assert "sequence" in store.keys
+    assert "loss_mask" in store.keys
+    assert "position_ids" in store.keys
+
+    dataset = DatasetFactory.load("sft", data_dir, window_size=8)
+    item = dataset[0]
+    assert "input_ids" in item
+    assert "target_ids" in item
+    assert "loss_mask" in item
+    assert "position_ids" in item
+    assert item["loss_mask"].dtype == torch.bool
+
+
+def test_jsonl_store_pipeline_config_roundtrip(base_test_env):
+    test_dir = base_test_env["test_dir"]
+    config_path = os.path.join(test_dir, "dataset_config.json")
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(
+            {
+                "tokenizer_path": os.path.join(test_dir, "tokenizer"),
+                "version": 1,
+                "input": {"sections": [{"field": "text", "action": "train"}]},
+                "mask": {"assistant": "train"},
+                "preprocessing": {"max_seq_len": 64},
+                "output": {"position_ids_mode": "doc_reset"},
+            },
+            f,
+            ensure_ascii=False,
+            indent=2,
+        )
+
+    with open(config_path, "r", encoding="utf-8") as f:
+        raw = json.load(f)
+    raw.pop("tokenizer_path")
+    config = PipelineConfig.from_dict(raw)
+    assert config.output.position_ids_mode == "doc_reset"
+    assert config.preprocessing.max_seq_len == 64
@@ -4,7 +4,7 @@ import torch

 from astrai.inference import (
    Allocator,
-    KVCache,
+    PageCache,
    PagePool,
    PrefixCache,
    Storage,
@@ -161,7 +161,7 @@ def test_task_table_pop():


 def test_kv_cache_task_extend_allocates():
-    cache = KVCache(
+    cache = PageCache(
        n_layers=1,
        n_pages=8,
        page_size=64,
@@ -177,7 +177,7 @@ def test_kv_cache_task_extend_allocates():


 def test_kv_cache_task_extend_fails_when_pool_full():
-    cache = KVCache(
+    cache = PageCache(
        n_layers=1,
        n_pages=2,
        page_size=64,
@@ -52,7 +52,7 @@ def create_train_config(
        batch_per_device: Batch size per device (default: 2)
        grad_accum_steps: Gradient accumulation steps (default: 1)
        max_grad_norm: Maximum gradient norm for clipping (default: 1.0)
-        ckpt_interval: Checkpoint save interval in iterations (default: 5)
+        ckpt_interval: Checkpoint save interval in optimizer steps (default: 5)
        random_seed: Random seed for reproducibility (default: 42)
        **kwargs: Additional arguments passed to TrainConfig

@@ -44,14 +44,14 @@ def test_early_stopping_simulation(base_test_env, early_stopping_dataset):
        pass

    # Resume from latest checkpoint
-    load_dir = os.path.join(base_test_env["test_dir"], "epoch_0_iter_2")
+    load_dir = os.path.join(base_test_env["test_dir"], "epoch_0_step_1")
    trainer = Trainer(train_config)
    trainer.train(resume_dir=load_dir)

-    # Verify checkpoint was saved at expected iteration
-    load_dir = os.path.join(base_test_env["test_dir"], "epoch_1_iter_10")
+    # Verify checkpoint was saved at expected step
+    load_dir = os.path.join(base_test_env["test_dir"], "epoch_1_step_5")
    import json

    with open(os.path.join(load_dir, "meta.json")) as f:
        meta = json.load(f)
-    assert meta["iteration"] == 10
+    assert meta["consumed_samples"] == 20
Author	SHA1	Message	Date
ViperEkura	bbe6ff2d8f	release : v1.3.8 - refactor: 重写 IFD 评估为三层架构，引入 BFD 装箱与自定义 attention mask 批处理打分 - refactor: 重写 HumanEval 评估为函数式流水线，修复测试超时与动态 pass@k - perf: 替换 paged KV cache 为 ContiguousCache，解码所有 group - feat: 新增 ROUGE 评估脚本、JSONL 数据集 store、stream_chat 参数 - fix: 修复 IFD token-set 不对称、SFT position_ids 默认值、文档边界保留	2026-07-05 19:12:33 +08:00
ViperEkura	db9b39b084	fix: resolve IFD token-set asymmetry and support single-token answers - Sentinel-anchored unconditional pass: both branches now predict the same N response tokens - Single-token responses (rl=1) fully supported - ctx_len tracked per sample; skip_reason replaces silent None - --per_token flag for per-token IFD breakdown	2026-07-05 17:48:26 +08:00
ViperEkura	849e1e00a3	refactor: clean up inference design patterns 1. KVCache base: add default task_cached/task_record_hashes, remove getattr from scheduler 2. Remove page_size param from scheduler constructor (ContiguousCache-only) 3. InferenceEngine expose cache param for KVCache injection 4. Rename page_cache -> kv_cache in Executor 5. Move stream_callback from Task to TaskManager._callbacks dict 6. TaskManager.clear_queues clears callbacks	2026-07-05 11:41:54 +08:00
ViperEkura	5416c2e8fb	perf: replace paged KV cache with contiguous ContiguousCache, decode all groups - Add KVCache/CacheView abstract base classes in cache.py - Add ContiguousCache (contiguous per-slot buffer, default) alongside PageCache (paged, renamed from old KVCache) - Merge make_table_tensor + bind into bind_tasks on KVCache interface - Remove task_cached/task_record_hashes from base class (PageCache-only) - Scheduler: decode all position groups instead of just the largest (eliminates 63% group skip rate) - Scheduler: accept optional cache param for swapping implementations - Model layer type hints use CacheView base class - Batch 1-32: 1-7% speedup from eliminating Storage.gather overhead - All 183 inference tests pass	2026-07-05 11:34:36 +08:00
ViperEkura	599a51f4f7	fix: reliable test timeout, separate generate/test phases, dynamic pass@k - Replace SIGALRM+exec() with subprocess.run(timeout=) for test execution - Add --test_only flag to skip generation and test existing completions - Add --generate_only flag for generation-only runs - Derive pass@k values from num_samples (filter k > n) - Support loading completions from array JSON (not just JSONL)	2026-07-05 08:47:30 +08:00
ViperEkura	17d6eaa2f2	refactor: rewrite humaneval evaluation with functional pipeline design - fix KeyError race condition in inference cache touch() - EvalConfig dataclass for centralized configuration - load->generate->extract->test->score->report pipeline - two-phase generation+testing for max GPU utilization - signal-based SIGALRM timeout protection for code exec - suppress subprocess stdout/stderr pollution	2026-07-05 07:58:28 +08:00
ViperEkura	2d908639e9	feat : add ROUGE evaluation script (manual impl, no deps) - ROUGE-1/2 via n-gram overlap (Counter) - ROUGE-L via LCS (DP) - CLI: python scripts/eval/evaluate_rouge.py --data_path ... --output ... - Library: compute_rouge(ref, cand) -> dict of precision/recall/f1	2026-07-05 01:15:01 +08:00
ViperEkura	c7158418dd	perf: add BFD bin-packing and custom attention mask to IFD batch scoring	2026-07-04 18:58:13 +08:00
ViperEkura	4d3c9341c1	refactor: rewrite IFD evaluation with clean three-layer architecture	2026-07-04 18:33:51 +08:00
ViperEkura	4e508afa2d	fix : SFT pipeline position_ids default & doc boundary preservation - change position_ids_mode default from "none" to "doc_reset" so SFT preprocessing always generates position_ids (was causing dataset load KeyError) - generate per-doc position_ids before packing (doc_reset mode), preserving document boundaries for BFD packing (cross-doc attention leak fix) - change _align_bucket padding from [1] to [0] to avoid accidentally training on loss_mask padding	2026-07-04 15:59:11 +08:00
ViperEkura	8999ca89b8	feat: add JSONL dataset store with on-the-fly tokenization - Add JsonlStore registered under "jsonl" in astrai/dataset/storage.py - Reuse PipelineConfig schema for JSONL dataset configuration - Update detect_format to recognize JSONL directories and files - Move save_h5/load_h5/save_bin/load_bin to astrai/serialization - Split astrai/serialization.py into checkpoint/dataset submodules - Add tests for JSONL detection, seq/SFT stores, and config roundtrip	2026-07-04 15:42:33 +08:00
ViperEkura	1adca39cd8	fix: handle long sequences and optimize IFD computation	2026-07-04 08:35:45 +08:00
ViperEkura	204873fa2f	fix: handle long sequences and optimize IFD computation	2026-07-04 08:23:32 +08:00
ViperEkura	a5c1de6b1b	feat: add model_path temperature top_p top_k max_tokens system_prompt args to stream_chat	2026-07-04 07:33:32 +08:00
ViperEkura	27524ad085	fix: reset sampler iter at epoch end so progress bar shows total after first epoch	2026-07-04 06:35:55 +08:00
ViperEkura	27d1921d9c	fix: scheduler division-by-zero, loss_mask bool - schedule.py: guard warmup_steps/lr_decay_steps against zero - strategy.py: use ~loss_mask instead of loss_mask==0 on bool tensor	2026-07-03 22:04:55 +08:00
ViperEkura	70c0e5de90	refactor: merge validation into MetricCallback, simplify progress bar to optimizer steps - Remove separate ValidationCallback, merge into MetricCallback - Progress bar now tracks optimizer steps instead of micro-steps - Remove unused log_interval config field and CLI flag - Fix validation all_reduce: use SUM(loss, count) instead of AVG - Simplify metric logging: always log every optimizer step - Add grad_norm display to progress bar	2026-07-03 21:43:08 +08:00
ViperEkura	dfb151537b	fix: ForwardRef._evaluate Python 3.12 compatibility	2026-07-03 18:41:19 +08:00
ViperEkura	500c605fad	fix: unify scheduler min_rate default to 0.01, clamp WSD warmup	2026-07-03 17:52:23 +08:00
ViperEkura	dc9faca3b1	fix: align docs with actual code (40+ inconsistencies) - Remove nonexistent Muon class from architecture diagram - Fix Checkpoint/TrainConfig/TrainContext field names (iteration -> consumed_samples, start_batch -> start_samples) - Add missing fields: neftune_alpha, val_split, grad_norm, optimizer_step, tool_calls/tools - Fix CLI param defaults: --log_interval 1, --metrics [loss,lr,grad_norm], --start_samples - Add missing scheduler CLI params; remove nonexistent --num_workers from preprocess docs - Fix inference SSE format, stats response keys, error codes to match actual server output - Fix preprocessing docs: BOS once, shard_0000 layout, from_json->from_file, GRPO prompts_mask - Fix dataflow detect_format/_normalize descriptions; correct callback order in training.md	2026-06-30 20:47:23 +08:00
ViperEkura	aabb0d83e9	refactor : replace iteration with consumed_samples - Replace context.iteration with consumed_samples (global sample count) - Add optimizer_step property derived from consumed_samples - Checkpoint meta.json stores consumed_samples, drops iteration - CLI --start_batch renamed to --start_samples (per-rank samples) - Checkpoint dir naming: epoch_X_step_Y instead of epoch_X_iter_Y - Metric log entries use step and consumed_samples fields - Backward compat removed (old iteration checkpoints unsupported)	2026-06-30 18:42:42 +08:00
ViperEkura	44579ea6dc	refactor : metric 日志改为以 optimizer step 为单位，默认每步记录 - log_interval 默认 100 -> 1，语义从 batch iteration 改为 optimizer step - step 指标从 on_batch_end 移到 on_optimizer_step，不受梯度累积影响 - JSONL 条目新增 step 字段，保留 iter - flush 落盘仍在 on_batch_end	2026-06-30 15:12:31 +08:00
ViperEkura	0f1fcb079f	refactor : grad_norm 指标简化，clip_grad_norm 移至 executor - metrics 默认加入 grad_norm，移除 grad_std/max/min/mean/nan_num - grad_norm 默认返回总 L2 范数，per_param=True 返回各参数范数 - clip_grad_norm 从 callback 移至 BaseExecutor/FSDPExecutor - FSDPExecutor 覆盖为 model.clip_grad_norm_() 保证分布式正确 - ctx_get_grad_norm 改为读取 context.grad_norm	2026-06-30 14:59:43 +08:00
ViperEkura	84d4769163	feat: SVD 有效秩/权重统计分析脚本	2026-06-29 21:39:22 +08:00
ViperEkura	bf09a35c95	feat: optimizer 参数分组，bias/norm 不做 weight decay	2026-06-27 16:30:34 +08:00
ViperEkura	6715461a36	chore : 升级 torch 2.11.0+cu128，移除自定义 Muon，修复 gloo device_id - torch 2.7.1-cu126 升级至 2.11.0-cu128，numpy 2.3.2 升级至 2.4.4 - 移除 astrai/trainer/optim.py，改用 torch.optim.Muon - parallel setup: gloo 后端不再传递 device_id，单卡多进程不再报错	2026-06-27 16:10:37 +08:00