docs: 修正文档中类名/字段名与代码不一致之处

- ModelConfig → AutoRegressiveLMConfig, Transformer → AutoRegressiveLM - 新增缺失类: EncoderConfig, EmbeddingEncoder, ConfigFactory, StorageFactory, ValidationCallback - TrainConfig/TrainContext/ChatCompletionRequest 补充缺失字段 - dataflow.md 中 create_storage → StorageFactory.create - 示例 --train_type=pt → seq 与代码一致
2026-05-17 20:25:07 +08:00
105 changed files with 2703 additions and 10789 deletions
@@ -5,10 +5,8 @@
 !*/

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

 # Allow GitHub files
 !/.github/**
@@ -5,7 +5,7 @@ Thank you for your interest in contributing! This document provides step-by-step
 ## Quick Start

 ```bash
-git clone https://github.com/ViperEkura/AstrAI.git
+git clone https://github.com/your-username/AstrAI.git
 cd AstrAI
 pip install -e ".[dev]"     # install with dev dependencies (pytest, ruff)
 ```
@@ -1,7 +1,7 @@
 # AstrAI Dockerfile - Multi-stage Build (Optimized)

 # Build stage - use base image with minimal build tools
-FROM ubuntu:24.04 AS builder
+FROM nvidia/cuda:12.6.0-base-ubuntu24.04 AS builder

 WORKDIR /app

@@ -18,22 +18,21 @@ RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-ins
 RUN python3.12 -m venv --copies /opt/venv
 ENV PATH="/opt/venv/bin:$PATH"

-# Copy source code and install (deps read from pyproject.toml)
+# Copy source code and install dependencies
 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/cu128
+    --extra-index-url https://download.pytorch.org/whl/cu126

 # Production stage
-FROM ubuntu:24.04 AS production
+FROM nvidia/cuda:12.6.0-base-ubuntu24.04 AS production

 WORKDIR /app

-# Install Python 3.12 runtime and healthcheck dependency
+# Install Python 3.12 runtime
 RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    python3.12 \
-    curl \
    && rm -rf /var/lib/apt/lists/*

 # Copy virtual environment from builder
@@ -9,9 +9,9 @@
 <div align="center">
  <img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="python">
  <img src="https://img.shields.io/badge/license-GPL--3.0-blue.svg" alt="license">
-  <img src="https://img.shields.io/github/v/release/ViperEkura/AstrAI?label=Release&color=76bad9" alt="release">
-  <img src="https://img.shields.io/github/stars/ViperEkura/AstrAI?style=flat&label=Stars&color=76bad9" alt="stars">
-  <img src="https://img.shields.io/github/forks/ViperEkura/AstrAI?style=flat&label=Forks&color=76bad9" alt="forks">
+  <img src="https://img.shields.io/github/v/release/ViperEkura/AstrAI?color=76bad9" alt="release">
+  <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.stargazers_count&label=stars&suffix=%20stars&color=76bad9" alt="stars">
+  <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.forks_count&label=forks&suffix=%20forks&color=76bad9" alt="forks">
 </div>
 <br>

@@ -28,8 +28,7 @@
 ## 📖 Table of Contents

 - [Features](#features)
- [Getting Started](#getting-started)
- [Demo](#demo)
+- [Quick Start](#quick-start)
 - [Documentation](#documentation)
 - [Contributing](#contributing)
 - [Community](#community)
@@ -50,50 +49,39 @@
 - 🤗 **HuggingFace-Style API**: AutoModel/AutoTokenizer APIs inspired by HuggingFace for easy model and tokenizer loading.
 - 🔌 **Dual API Compatibility**: Supports both OpenAI and Anthropic chat completion APIs out of the box.

-### Getting Started
+### Quick Start

-End-to-end walkthrough in 5 steps:
-
-**1. Install**
+#### Installation

 ```bash
 git clone https://github.com/ViperEkura/AstrAI.git
 cd AstrAI
 pip install -e .
-# pip install -e ".[dev]"    # optional: dev dependencies (pytest, ruff)
 ```

-**2. Download model**
+For development dependencies:

 ```bash
-python scripts/demo/download.py    # downloads 1B checkpoint to params/
+pip install -e ".[dev]"
 ```

-**3. Preprocess data**
+#### Download Pre-trained Model

-Create `pretrain.json` (preprocessing config for `seq` strategy):
-
-```json
-{
-    "version": 1,
-    "input": {"sections": [{"field": "text", "action": "train"}]},
-    "preprocessing": {"max_seq_len": 2048},
-    "output": {"storage_format": "bin"}
-}
-```
+Download pre-trained model weights (1B bilingual checkpoint) to `params/`:

 ```bash
-python scripts/tools/preprocess.py data/*.jsonl -o output/ -c pretrain.json
+python scripts/demo/download.py
 ```

-**4. Train**
+Or download manually from [HuggingFace](https://huggingface.co/ViperEk/KHAOSZ) into `params/`.
+
+#### Train a Model

 ```bash
 export CUDA_VISIBLE_DEVICES=0,1,2,3

 nohup python scripts/tools/train.py \
    --nprocs=4 \
-    --parallel_mode=ddp \
    --train_type=seq \
    --data_root_path=/path/to/dataset \
    --param_path=/path/to/model \
@@ -113,54 +101,15 @@ nohup python scripts/tools/train.py \
    > out.log 2> err.log &
 ```

-**5. Serve & query**
+Full reference at [Parameter Guide](assets/docs/params.md).

-```bash
-# Terminal 1: start server
-python scripts/tools/server.py --param_path ./params --device cuda
-
-# Terminal 2: query
-curl http://localhost:8000/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":512}'
-```
-
-### Demo
-
-Check out the demos in the `scripts/demo/` folder:
-
-```bash
-# Download model weights (required before running demos)
-python scripts/demo/download.py                      # model → params/
-
-# Interactive streaming chat (multi-turn, maintains history)
-python scripts/demo/stream_chat.py
-# Type your message after >>, type !exit to quit
-
-# Batch generation (5 hardcoded prompts, non-streaming)
-python scripts/demo/generate_batch.py
-
-# Single-prompt autoregressive streaming
-python scripts/demo/generate_ar.py
-```
-
-All generation demos use `temperature=0.8`, `top_p=0.95`, `top_k=50`, `max_tokens=2048` by default and require `params/` to contain model weights (run `download.py` first).
-
-Watch a video walkthrough on [bilibili](https://www.bilibili.com/video/BV1fuLB6yEj6).
-
---
-
-See [Documentation](#documentation) for full references beyond the examples above.
-
-#### Text Generation
-
-Batch generation from a JSONL file:
+#### Generate Text

 ```bash
 python scripts/tools/generate.py \
-    --param_path ./params \
-    --input_json_file input.jsonl \
-    --output_json_file output.jsonl
+    --param_path /path/to/model \
+    --input_json_file /path/to/input.json \
+    --output_json_file /path/to/output.json
 ```

 #### Docker
@@ -174,6 +123,9 @@ docker build -t astrai:latest .
 # Run with GPU support
 docker run --gpus all -it astrai:latest

+# Run with specific GPUs
+docker run --gpus '"device=0,1"' -it astrai:latest
+
 # Run inference server
 docker run --gpus all -p 8000:8000 astrai:latest \
  python -m scripts.tools.server --port 8000 --device cuda
@@ -190,42 +142,88 @@ docker compose --profile cpu up -d

 > **Note**: `--gpus all` is required for CUDA support. Without it, `torch.cuda.is_available()` will return `False`.

-#### HTTP API Examples
+#### Start HTTP Server

-Additional request examples beyond the [Getting Started](#getting-started) flow:
+Start the inference server with OpenAI and Anthropic-compatible HTTP API:

 ```bash
+python -m scripts.tools.server --port 8000 --device cuda
+```
+
+Make requests:
+
+```bash
+# OpenAI-compatible
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "Hello"}],
+    "max_tokens": 512
+  }'
+
 # OpenAI-compatible streaming
 curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
-  -d '{"messages":[{"role":"user","content":"Tell a story"}],"stream":true,"max_tokens":500}'
+  -d '{
+    "messages": [{"role": "user", "content": "Tell a story"}],
+    "stream": true,
+    "max_tokens": 500
+  }'

 # Anthropic-compatible
 curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
-  -d '{"model":"astrai","system":"You are a helpful assistant.","messages":[{"role":"user","content":"Hello"}],"max_tokens":512}'
+  -d '{
+    "model": "astrai",
+    "system": "You are a helpful assistant.",
+    "messages": [{"role": "user", "content": "Hello"}],
+    "max_tokens": 512
+  }'

 # Anthropic-compatible streaming with stop sequences
 curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
-  -d '{"model":"astrai","messages":[{"role":"user","content":"Write a story"}],"max_tokens":500,"stream":true,"stop_sequences":["The end"]}'
+  -d '{
+    "model": "astrai",
+    "messages": [{"role": "user", "content": "Write a story"}],
+    "max_tokens": 500,
+    "stream": true,
+    "stop_sequences": ["The end"]
+  }'

 # Health check
 curl http://localhost:8000/health
 ```

-See [Inference Guide](assets/docs/inference.md) for SSE streaming format, error codes, and stats endpoint.
+#### Demo
+
+Check out the demos in the `scripts/demo/` folder:
+
+```bash
+# Download pre‑processed data (required before running demos)
+python scripts/demo/download.py
+
+# Interactive streaming chat
+python scripts/demo/stream_chat.py
+
+# Batch generation
+python scripts/demo/generate_batch.py
+
+# Auto‑regressive generation
+python scripts/demo/generate_ar.py
+```
+
+Watch a video walkthrough on [bilibili](https://www.bilibili.com/video/BV1z5RPYHEkd).

 ### Documentation

 | Document | Description |
 |----------|-------------|
-| [CLI Reference](./assets/docs/params.md) | Parameters for all CLI tools (train, server, generate, preprocess) |
+| [Parameter Guide](./assets/docs/params.md) | Training & inference parameters |
 | [Architecture](./assets/docs/architecture.md) | System architecture, class diagram & design patterns |
 | [Training](./assets/docs/training.md) | Training loop, strategies & formulas |
 | [Inference](./assets/docs/inference.md) | KVCache, continuous batching, sampling & HTTP API |
 | [Data Flow](./assets/docs/dataflow.md) | Data pipeline, storage backends & dataset architecture |
-| [Preprocessing](./assets/docs/preprocessing.md) | Declarative JSON-driven data preprocessing |

 ### Contributing

@@ -15,9 +15,9 @@
 <div align="center">
  <img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="python">
  <img src="https://img.shields.io/badge/license-GPL--3.0-blue.svg" alt="license">
-  <img src="https://img.shields.io/github/v/release/ViperEkura/AstrAI?label=Release&color=76bad9" alt="release">
-  <img src="https://img.shields.io/github/stars/ViperEkura/AstrAI?style=flat&label=Stars&color=76bad9" alt="stars">
-  <img src="https://img.shields.io/github/forks/ViperEkura/AstrAI?style=flat&label=Forks&color=76bad9" alt="forks">
+  <img src="https://img.shields.io/github/v/release/ViperEkura/AstrAI?color=76bad9" alt="release">
+  <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.stargazers_count&label=stars&suffix=%20stars&color=76bad9" alt="stars">
+  <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.forks_count&label=forks&suffix=%20forks&color=76bad9" alt="forks">
 </div>

 <br>
@@ -34,8 +34,7 @@
 ## 📖 目录

 - [特性](#特性)
- [快速上手](#快速上手)
- [演示](#演示)
+- [快速开始](#快速开始)
 - [文档](#文档)
 - [贡献](#贡献)
 - [社区](#社区)
@@ -56,50 +55,39 @@
 - 🤗 **HuggingFace 风格 API**: 类 HuggingFace 的 AutoModel/AutoTokenizer 接口，方便加载模型和分词器。
 - 🔌 **双 API 兼容**: 同时支持 OpenAI 和 Anthropic 聊天补全 API，开箱即用。

-### 快速上手
+### 快速开始

-端到端演示，只需 5 步：
-
-**1. 安装**
+#### 安装

 ```bash
 git clone https://github.com/ViperEkura/AstrAI.git
 cd AstrAI
 pip install -e .
-# pip install -e ".[dev]"    # 可选：开发依赖（pytest, ruff）
 ```

-**2. 下载模型**
+安装开发依赖：

 ```bash
-python scripts/demo/download.py    # 下载 1B 检查点到 params/
+pip install -e ".[dev]"
 ```

-**3. 预处理数据**
+#### 下载预训练模型

-创建 `pretrain.json`（`seq` 策略的预处理配置）：
-
-```json
-{
-    "version": 1,
-    "input": {"sections": [{"field": "text", "action": "train"}]},
-    "preprocessing": {"max_seq_len": 2048},
-    "output": {"storage_format": "bin"}
-}
-```
+下载预训练模型权重（1B 双语检查点）到 `params/` 目录：

 ```bash
-python scripts/tools/preprocess.py data/*.jsonl -o output/ -c pretrain.json
+python scripts/demo/download.py
 ```

-**4. 训练**
+或从 [HuggingFace](https://huggingface.co/ViperEk/KHAOSZ) 手动下载放入 `params/`。
+
+#### 训练模型

 ```bash
 export CUDA_VISIBLE_DEVICES=0,1,2,3

 nohup python scripts/tools/train.py \
    --nprocs=4 \
-    --parallel_mode=ddp \
    --train_type=seq \
    --data_root_path=/path/to/dataset \
    --param_path=/path/to/model \
@@ -119,54 +107,15 @@ nohup python scripts/tools/train.py \
    > out.log 2> err.log &
 ```

-**5. 启动服务并调用**
-
-```bash
-# 终端 1：启动服务
-python scripts/tools/server.py --param_path ./params --device cuda
-
-# 终端 2：发起请求
-curl http://localhost:8000/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"messages":[{"role":"user","content":"你好"}],"max_tokens":512}'
-```
-
-### 演示
-
-查看 `scripts/demo/` 文件夹中的演示：
-
-```bash
-# 下载模型权重（运行演示前必需）
-python scripts/demo/download.py                      # model → params/
-
-# 交互式流式聊天（多轮对话，保持历史记录）
-python scripts/demo/stream_chat.py
-# 在 >> 后输入消息，输入 !exit 退出
-
-# 批量生成（5 条硬编码提示词，非流式）
-python scripts/demo/generate_batch.py
-
-# 单条提示词自回归流式生成
-python scripts/demo/generate_ar.py
-```
-
-所有生成演示默认使用 `temperature=0.8`、`top_p=0.95`、`top_k=50`、`max_tokens=2048`，需要 `params/` 目录包含模型权重（请先运行 `download.py`）。
-
-观看 [bilibili](https://www.bilibili.com/video/BV1fuLB6yEj6) 上的视频演示。
-
---
-
-更多选项请参考[文档](#文档)。
+完整参数列表见[参数说明](./params.md)。

 #### 文本生成

-从 JSONL 文件批量生成：
-
 ```bash
 python scripts/tools/generate.py \
-    --param_path ./params \
-    --input_json_file input.jsonl \
-    --output_json_file output.jsonl
+    --param_path /path/to/model \
+    --input_json_file /path/to/input.json \
+    --output_json_file /path/to/output.json
 ```

 #### Docker
@@ -180,6 +129,9 @@ docker build -t astrai:latest .
 # 启用 GPU 运行
 docker run --gpus all -it astrai:latest

+# 指定特定 GPU
+docker run --gpus '"device=0,1"' -it astrai:latest
+
 # 运行推理服务
 docker run --gpus all -p 8000:8000 astrai:latest \
  python -m scripts.tools.server --port 8000 --device cuda
@@ -196,42 +148,88 @@ docker compose --profile cpu up -d

 > **注意**: 必须使用 `--gpus all` 才能启用 CUDA 支持，否则 `torch.cuda.is_available()` 将返回 `False`。

-#### HTTP API 示例
+#### 启动 HTTP 服务

-除[快速上手](#快速上手)流程外，更多请求示例：
+启动推理服务器，支持 OpenAI 和 Anthropic 兼容的 HTTP API：

 ```bash
+python -m scripts.tools.server --port 8000 --device cuda
+```
+
+发起请求：
+
+```bash
+# OpenAI 兼容
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "你好"}],
+    "max_tokens": 512
+  }'
+
 # OpenAI 兼容流式
 curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
-  -d '{"messages":[{"role":"user","content":"讲个故事"}],"stream":true,"max_tokens":500}'
+  -d '{
+    "messages": [{"role": "user", "content": "讲个故事"}],
+    "stream": true,
+    "max_tokens": 500
+  }'

 # Anthropic 兼容
 curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
-  -d '{"model":"astrai","system":"你是一个乐于助人的助手。","messages":[{"role":"user","content":"你好"}],"max_tokens":512}'
+  -d '{
+    "model": "astrai",
+    "system": "你是一个乐于助人的助手。",
+    "messages": [{"role": "user", "content": "你好"}],
+    "max_tokens": 512
+  }'

 # Anthropic 兼容流式并设置停止序列
 curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
-  -d '{"model":"astrai","messages":[{"role":"user","content":"写个故事"}],"max_tokens":500,"stream":true,"stop_sequences":["结束"]}'
+  -d '{
+    "model": "astrai",
+    "messages": [{"role": "user", "content": "写个故事"}],
+    "max_tokens": 500,
+    "stream": true,
+    "stop_sequences": ["结束"]
+  }'

 # 健康检查
 curl http://localhost:8000/health
 ```

-SSE 流式格式、错误码和统计端点详见[推理文档](./inference.md)。
+#### 演示
+
+查看 `scripts/demo/` 文件夹中的演示：
+
+```bash
+# 下载预处理数据（运行演示前必需）
+python scripts/demo/download.py
+
+# 交互式流式聊天
+python scripts/demo/stream_chat.py
+
+# 批量生成
+python scripts/demo/generate_batch.py
+
+# 自回归生成
+python scripts/demo/generate_ar.py
+```
+
+观看 [bilibili](https://www.bilibili.com/video/BV1z5RPYHEkd) 上的视频演示。

 ### 文档

 | 文档 | 说明 |
 |------|------|
-| [CLI 参考](./params.md) | 所有 CLI 工具参数（训练、服务、生成、预处理） |
+| [参数说明](./params.md) | 训练与推理参数配置 |
 | [架构文档](./architecture.md) | 系统架构、类图与设计模式 |
 | [训练文档](./training.md) | 训练循环、策略与公式 |
 | [推理文档](./inference.md) | KVCache、连续批处理、采样与 HTTP API |
 | [数据流程](./dataflow.md) | 数据管道、存储后端与数据集架构 |
-| [数据预处理](./preprocessing.md) | 声明式 JSON 驱动数据预处理 |

 ### 贡献

@@ -1,98 +1,46 @@
 # Data Flow

-This document describes the data pipeline: from raw text to model input tensors. For creating preprocessing configs, see [Preprocessing Guide](preprocessing.md).
-
-## Contents
-
- [Overview](#overview)
- [Data Preparation](#data-preparation) — tokenization, format detection, backends
- [Data Keys by Training Type](#data-keys-by-training-type)
- [Dataset Architecture](#dataset-architecture)
- [Sampler](#sampler)
- [DataLoader](#dataloader)
+This document describes the data pipeline: from raw text to model input tensors.

 ## Overview

 ```
-JSONL Lines → Pipeline (mask builder) → Tokenized Tensors
-                                              ↓
-                                      .h5 or .bin storage
-                                              ↓
-                                      Store.load()
-                                              ↓
-                                      Store.fetch(begin, end, keys)
-                                              ↓
-                                      BaseDataset.__getitem__(idx)
-                                              ↓
-                                      Sampler → DataLoader → Training / Inference
+Raw Text → AutoTokenizer → Token IDs → .h5/.json → Dataset → Sampler → DataLoader → Training/Inference
 ```

 ## Data Preparation

-Raw text is tokenized via `AutoTokenizer.encode()` and saved as HDF5 (`.h5`) or binary (`.bin` + `meta.json`) files with keyed tensor groups.
-
-### Tokenization
-
-The `Pipeline` reads JSONL lines, applies the mask builder (see [Preprocessing](preprocessing.md)), and produces flat token sequences:
-
-```python
-# Per JSONL line: messages → chat template → token IDs + loss mask
-tokens = tokenizer.encode(rendered_text)        # List[int]
-loss_mask = [0, 0, 0, 1, 1, 1, 1, 1, 1]        # 0=masked, 1=train
-# Stored as flat tensors, packed with other lines by packing strategy
-```
-
-The output `meta.json` records the storage format, key names, dtype, total token count, and tensor shapes for each shard.
-
-### Format Detection
-
-`detect_format(load_path)` inspects the path:
-
- 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
+Raw text is tokenized via `AutoTokenizer.encode()` and saved as HDF5 (`.h5`) or JSON (`.json`/`.jsonl`) files with keyed tensor groups.

 Storage format is auto-detected by `detect_format()`; backends are dispatched via registry:

 ```
-StoreFactory.create("h5")  → H5Store
-StoreFactory.create("bin") → MmapStore
+StorageFactory.create("h5")   → H5Storage
+StorageFactory.create("json") → JSONStorage
 ```

-**H5Store**: Reads HDF5 files, supports `share_memory_()` for multi-process DataLoader workers (copies tensors to shared memory).
-
-**MmapStore**: Memory-maps `.bin` files. OS page cache sharing is native — no explicit `share_memory_()` needed. Uses `torch.from_numpy(np.memmap(...))`.
-
-Both backends normalise tensors into `Store._data[Dict[str, List[Tensor]]]` + `Store._cum[Dict[str, List[int]]]` (cumulative lengths for bisect-based indexing).
+Both support shared memory via `.share_memory_()`.

 ## Data Keys by Training Type

 | Type | Storage Keys |
 |------|-------------|
 | `seq` | `sequence` (→ input_ids, target_ids via offset-by-1) |
-| `sft` | `sequence`, `loss_mask`, `position_ids` |
+| `sft` | `sequence`, `loss_mask` |
 | `dpo` | `chosen`, `rejected`, `chosen_mask`, `rejected_mask` |
 | `grpo` | `prompts`, `responses`, `masks`, `rewards` |

 ## Dataset Architecture

 ```
-DatasetFactory.load(train_type, load_path, window_size, stride=None, storage_type=None)
-  → BaseDataset.load(load_path, storage_type=None)
-    → detect_format(load_path)
-    → StoreFactory.create(storage_type)
-    → Store.load(load_path)
-      → _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)
-            → Store.fetch(begin, end, keys) → Tensor / Dict[str, Tensor]
+DatasetFactory.load(train_type, path, window_size, stride)
+  → StorageFactory.create(detect_format(path))
+    → MultiSegmentFetcher(BaseSegmentFetcher per key)
+      → BaseDataset.__getitem__(idx)
+        → sliding window [begin, end) via get_index(idx)
 ```

-`window_size` = max input length, `stride` = step between consecutive samples (defaults to `window_size`, optional). `storage_type` defaults to `None` (auto-detect via `detect_format`).
-
-`Store.fetch(begin, end, keys)` accepts a single key (`str`) returning a `Tensor`, or a list of keys returning `Dict[str, Tensor]`. Internally uses `bisect` across multi-segment tensors. Raises `RuntimeError("Store not loaded")` if called before `load()`.
+`window_size` = max input length, `stride` = step between consecutive samples.

 ## Sampler

@@ -106,4 +54,4 @@ DatasetFactory.load(train_type, load_path, window_size, stride=None, storage_typ

 Standard PyTorch `DataLoader` with configurable `batch_size`, `num_workers`, `pin_memory`, `prefetch_factor`. Sampler produces indices; dataloader fetches tensor batches via `__getitem__`.

-> Document Update Time: 2026-06-19
+> Document Update Time: 2026-05-17
@@ -1,16 +1,5 @@
 # Inference

-## Contents
-
- [KV Cache](#kv-cache)
- [KVCache System](#kvcache-system)
- [Continuous Batching](#continuous-batching)
- [Sampling](#sampling-strategy-pattern)
- [Protocol Handlers](#protocol-handlers-strategy-pattern)
- [Engine & GenerateResult](#engine--generateresult)
- [HTTP API](#http-api) — endpoints, SSE, errors, stats
- [Engine API](#engine-api)
-
 ## KV Cache

 At decode time, only the last query token matters. All previous K/V are cached to avoid recomputation:
@@ -23,16 +12,16 @@ RoPE is applied **before** KV cache write, not after — otherwise position enco

 ## KVCache System

-Seven classes working together:
+Six classes working together:

 ```
 KVCache (facade)
-  ├── PagePool         orchestrates page allocation + prefix matching
-  │     ├── Allocator   bitmask-based page allocator + ref-count + LRU eviction (inside PagePool)
-  │     └── PrefixCache hash-based prefix matching (page_hash via polynomial hash) (inside PagePool)
+  ├── Allocator        bitmask-based page allocator + ref-count + LRU eviction
+  ├── PrefixCache      hash-based prefix matching (page_hash via rolling hash)
+  ├── PagePool         orchestrates Allocator + PrefixCache
  ├── TaskTable        maps task_id → page_table + cached token count
  ├── Storage          k_cache / v_cache tensors (n_layers × n_pages × page_size × n_kv_heads × head_dim)
-  └── KvcacheView      bundles Storage + page_table + total_len for attention layers (returned by bind())
+  └── KvcacheView      bundles Storage + page_table + total_len for attention layers
 ```

 `KVCache.bind(page_table, total_len)` returns a `KvcacheView` used by attention layers via `write()` / `gather()`.
@@ -51,33 +40,26 @@ KVCache (facade)
 ## Sampling (Strategy Pattern)

 ```
-BaseSamplingStrategy (ABC)
-  ├── TemperatureStrategy
-  ├── TopKStrategy
-  ├── TopPStrategy
-  └── SamplingPipeline
+BaseSamplingStrategy → TemperatureStrategy → TopKStrategy → TopPStrategy
 ```

 `SamplingPipeline` composes them: Temperature → Top-K → Top-P → softmax → multinomial.  
 `sample()` is a convenience shortcut for one-shot usage.

-## Protocol Handlers (Strategy Pattern)
+## Protocol Handlers (Template Method)

 ```python
-class ProtocolHandler:  # concrete orchestrator
-    def __init__(self, request, engine, builder): ...
-    async def handle(self):
-        prompt, ctx, stops = builder.prepare(request, engine)
+class ProtocolHandler(ABC):
+    def handle(self):
+        ctx = StreamContext(...)
        agen = engine.generate_async(prompt, ...)
-        if stream: self._handle_stream(agen, ctx, stops)
-        else:      return await self._handle_non_stream(agen, ctx, stops)
+        if stream: self._handle_stream(agen, ctx)
+        else:      self._handle_non_stream(agen, ctx)
 ```

-`ResponseBuilder` (ABC): `prepare()`, `format_stream_start()`, `format_chunk()`, `format_stream_end()`, `format_response()`.
+Subclass hooks: `build_prompt()`, `create_response_id()`, `format_stream_start/token/end()`, `format_non_stream_response()`.

-`OpenAIResponseBuilder` → `/v1/chat/completions`, `AnthropicResponseBuilder` → `/v1/messages`.
-
-Adding a protocol = one builder file, no handler subclassing needed.
+`OpenAIHandler` → `/v1/chat/completions`, `AnthropicHandler` → `/v1/messages`.

 ## Engine & GenerateResult

@@ -85,9 +67,7 @@ Adding a protocol = one builder file, no handler subclassing needed.
 InferenceEngine
  ├── generate(prompt, stream, ...) → str | List[str] | Generator
  ├── generate_with_request(req)    → same
-  ├── generate_async(prompt, ...)   → AsyncGenerator
-  ├── get_stats()                   → Dict
-  └── shutdown()
+  └── generate_async(prompt, ...)   → AsyncGenerator
 ```

 `GenerateResult` uses `Condition` for non-streaming (`wait_completion()`) and `Event` for streaming (`wait()`). Stream callback is `cb(token)`.
@@ -114,14 +94,12 @@ Response:
 {
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
-  "created": 1717000000,
-  "model": "astrai",
-  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
+  "choices": [{"message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 5, "completion_tokens": 10, "total_tokens": 15}
 }
 ```

-Streaming SSE: `object: "chat.completion.chunk"` — starts with role delta, then token chunks, ends with finish chunk + usage stats, then `data: [DONE]`.
+Streaming SSE: `data: {"choices":[{"delta":{"role":"assistant"}}]}` → token chunks → `data: [DONE]`

 ### Anthropic

@@ -138,90 +116,12 @@ Supports `stop_sequences` and streaming via `event: content_block_delta`.
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
 | `messages` | List[dict] | required | Chat messages (role, content) |
-| `top_k` | int | 50 | Top-k count |
+| `temperature` | float | 1.0 | Sampling temperature (0.0–2.0) |
 | `top_p` | float | 1.0 | Nucleus threshold |
-| `temperature` | float | 1.0 | Sampling temperature (> 0.0) |
-| `max_tokens` | Optional[int] | None | Max generation length |
+| `top_k` | int | 50 | Top-k count |
+| `max_tokens` | int | None | Max generation length |
 | `stream` | bool | False | Stream output |

-### SSE Streaming Format
-
-**OpenAI** (`/v1/chat/completions`, `stream=true`):
-
-```
-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","created":0,"model":"astrai",
-       "choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
-
-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]
-```
-
-**Anthropic** (`/v1/messages`, `stream=true`):
-
-```
-event: message_start
-data: {"type":"message_start","message":{"id":"msg_...","model":"astrai","role":"assistant",
-       "content":[],"usage":{"input_tokens":0}}}
-
-event: content_block_start
-data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
-
-event: content_block_delta
-data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
-
-event: content_block_stop
-data: {"type":"content_block_stop","index":0}
-
-event: message_delta
-data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{...}}
-
-event: message_stop
-data: {"type":"message_stop"}
-```
-
-### Error Responses
-
-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 |
-| 422 | Unprocessable entity (Pydantic validation) |
-| 503 | Service unavailable (model not loaded, engine not ready) |
-
-Error response body (503):
-
-```json
-{
-    "detail": "Engine not initialized"
-}
-```
-
-### Stats Endpoint
-
-```
-GET /stats
-```
-
-Response:
-
-```json
-{
-    "total_tasks": 128,
-    "total_tokens": 10240,
-    "active_tasks": 3,
-    "waiting_queue": 2
-}
-```
-
 ## Engine API

 ```python
@@ -234,8 +134,7 @@ engine.generate("Hello", stream=True)           # -> Generator[str]
 engine.generate(["A", "B"], stream=True)        # -> Generator[Tuple[int, str]]

 # Async
-async for token in engine.generate_async("Hello", ...):    # -> AsyncGenerator[str]
-    print(token)
+await engine.generate_async("Hello", ...)       # -> AsyncGenerator[str]
 ```

-> Document Update Time: 2026-06-19
+> Document Update Time: 2026-05-17
@@ -1,11 +1,4 @@
-# CLI Parameter Reference
-
-## Contents
-
- [Training Parameters](#training-parameters)
- [Inference Server](#inference-server-serverpy)
- [Generate](#generate-generatepy)
- [Preprocess](#preprocess-preprocesspy)
+# Parameter Documentation

 ## Training Parameters

@@ -53,63 +46,25 @@
 | `--ckpt_interval` | Iterations between checkpoints | 5000 |
 | `--ckpt_dir` | Checkpoint save directory | checkpoint |
 | `--start_epoch` | Resume from epoch (0 = from scratch) | 0 |
-| `--start_samples` | Resume from sample count per rank | 0 |
-
-### Validation
-
-| Parameter | Description | Default |
-|-----------|-------------|---------|
-| `--val_split` | Ratio to split from training dataset for validation (e.g. 0.05) | None |
-| `--val_step` | Number of optimizer steps between validation runs | 1000 |
-
-### Logging
-
-| Parameter | Description | Default |
-|-----------|-------------|---------|
-| `--log_dir` | Directory for metric logs | checkpoint/logs |
-| `--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
-
-| Parameter | Description | Default |
-|-----------|-------------|---------|
-| `--gradient_checkpointing` | Enable activation checkpointing for DecoderBlock modules | False |
+| `--start_batch` | Resume from batch iteration | 0 |

 ### Distributed Training

 | Parameter | Description | Default |
 |-----------|-------------|---------|
 | `--nprocs` | Number of GPUs / processes | 1 |
-| `--parallel_mode` | Parallel strategy (`none`, `ddp`, or `fsdp`) | none |
 | `--device_type` | Device type | cuda |
-| `--start_method` | Multiprocessing start method (`spawn`, `fork`, `forkserver`) | spawn |
-| `--backend` | Distributed training backend | nccl |
-| `--master_addr` | Master node address | localhost |
-| `--master_port` | Master node port | 29500 |

 ### Strategy-specific

 | Parameter | Description | Default | Used by |
 |-----------|-------------|---------|---------|
 | `--dpo_beta` | DPO beta value | 0.1 | `dpo` |
-| `--label_smoothing` | Label smoothing for cross-entropy loss | 0.0 | `seq`, `sft` |
+| `--label_smoothing` | Label smoothing for cross-entropy loss | 0.05 | `seq`, `sft` |
 | `--group_size` | GRPO group size | 4 | `grpo` |
 | `--grpo_clip_eps` | GRPO clipping epsilon | 0.2 | `grpo` |
 | `--grpo_kl_coef` | GRPO KL penalty coefficient | 0.01 | `grpo` |
 | `--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

@@ -118,7 +73,6 @@ export CUDA_VISIBLE_DEVICES=0,1,2,3

 nohup python scripts/tools/train.py \
    --nprocs=4 \
-    --parallel_mode=ddp \
    --train_type=seq \
    --data_root_path=/path/to/dataset \
    --param_path=/path/to/model \
@@ -140,64 +94,4 @@ nohup python scripts/tools/train.py \

 ---

-## Inference Server (`server.py`)
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `--host` | str | `0.0.0.0` | Host address |
-| `--port` | int | `8000` | Port number |
-| `--param_path` | path | `project_root/params` | Path to model parameters |
-| `--device` | str | `cuda` | Device to load model on |
-| `--dtype` | str | `bfloat16` | Model weights dtype (`bfloat16`, `float16`, `float32`) |
-| `--max_batch_size` | int | `16` | Maximum batch size for continuous batching |
-| `--reload` | flag | `False` | Enable auto-reload for development |
-
-Usage:
-```bash
-python scripts/tools/server.py --param_path ./params --device cuda --dtype bfloat16
-```
-
-See [Inference Guide](inference.md) for HTTP API documentation.
-
-## Generate (`generate.py`)
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `--param_path` | str | required | Path to the model directory |
-| `--input_json_file` | str | required | Path to the input JSONL file |
-| `--output_json_file` | str | required | Path to the output JSONL file |
-| `--question_key` | str | `question` | Key for the question in input JSON |
-| `--response_key` | str | `response` | Key for the response in output JSON |
-| `--temperature` | float | `0.60` | Sampling temperature |
-| `--top_k` | int | `30` | Top-k filtering |
-| `--top_p` | float | `0.95` | Nucleus sampling threshold |
-| `--batch_size` | int | `1` | Batch size for generation |
-| `--max_tokens` | int | model config `max_len` | Maximum tokens to generate |
-
-Usage:
-```bash
-python scripts/tools/generate.py \
-    --param_path ./params \
-    --input_json_file input.jsonl \
-    --output_json_file output.jsonl
-```
-
-## Preprocess (`preprocess.py`)
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `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) |
-| `--tokenizer_path` | str | `params` | Path to tokenizer directory |
-
-Usage:
-```bash
-python scripts/tools/preprocess.py data/*.jsonl -o output/ -c sft.json
-```
-
-See [Preprocessing Guide](preprocessing.md) for config file format and examples.
-
---
-
-> Document Update Time: 2026-06-19
+> Document Update Time: 2026-05-17
@@ -1,364 +0,0 @@
-# Preprocessing Pipeline
-
-Declarative JSON-driven data preprocessing. One `SectionedMaskBuilder` handles all formats via `input.sections` (single-output) or `input.sources` (multi-output).
-
-## Contents
-
- [Philosophy](#philosophy)
- [Config Structure](#config-structure)
- [Quick Start](#quick-start) — SFT Chat, SFT Instruction, Pretrain, DPO, GRPO examples
- [Configuration Reference](#configuration-reference) — all fields
- [Mask Algorithm](#mask-algorithm)
- [Output Layout](#output-layout)
- [CLI](#cli)
- [Python API](#python-api)
-
-## Philosophy
-
-| Component | Responsibility |
-|-----------|---------------|
-| `tokenizer_config.json` (`chat_template`) | Formatting -- how roles become tokens |
-| `pipeline.json` (`mask`) | Masking -- which roles participate in training |
-
-A single config file captures the entire pipeline, reusable and version-controllable.
-
-## Config Structure
-
-```json
-{
-  "version":       1,
-  "input":         {},   // sections (single) or sources (multi)
-  "mask":          {},   // role -> "train" | "mask"
-  "mask_default":  "mask",
-  "preprocessing": {},
-  "output":        {}
-}
-```
-
-### Section Fields
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `field` | str | -- | JSONL key to read |
-| `action` | str | -- | `"train"` / `"mask"` / `"$role"` |
-| `template` | bool | `false` | Apply `chat_template` per message |
-| `add_special_tokens` | bool | `true` for first non-template section | Add special tokens during encode |
-
-### Source Fields (multi-output mode)
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `sections` | list[dict] | -- | Same as single-output section list |
-| `list_field` | bool | `false` | JSONL field holds a list; tokenise each element |
-| `mask_key` | str | `"{key}_mask"` | Explicit output key for loss mask |
-
---
-
-## Quick Start
-
-### SFT Chat
-
-Input JSONL:
-
-```json
-{"messages": [{"role": "system", "content": "You are helpful."}, {"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello!"}]}
-```
-
-Config:
-
-```json
-{
-  "input": {
-    "sections": [
-      {"field": "messages", "action": "$role", "template": true}
-    ]
-  },
-  "mask": {
-    "system": "mask",
-    "user": "mask",
-    "assistant": "train"
-  },
-  "mask_default": "mask",
-  "preprocessing": {
-    "max_seq_len": 2048
-  },
-  "output": {
-    "storage_format": "bin",
-    "dtype": {"loss_mask": "bool"}
-  }
-}
-```
-
-Output keys: `sequence` (int32), `loss_mask` (bool)
-
-### SFT Instruction
-
-Input JSONL:
-
-```json
-{"prompt": "Translate to French: Hello", "response": "Bonjour"}
-```
-
-Config:
-
-```json
-{
-  "input": {
-    "sections": [
-      {"field": "prompt",   "action": "mask", "add_special_tokens": true},
-      {"field": "response", "action": "train"}
-    ]
-  },
-  "mask_default": "mask",
-  "preprocessing": {
-    "max_seq_len": 2048
-  }
-}
-```
-
-Output keys: `sequence`, `loss_mask`
-
-### Pretrain
-
-Input JSONL:
-
-```json
-{"text": "Artificial Intelligence is a field of computer science..."}
-```
-
-Config:
-
-```json
-{
-  "input": {
-    "sections": [
-      {"field": "text", "action": "train"}
-    ]
-  },
-  "preprocessing": {
-    "max_seq_len": 8192,
-    "min_chars": 100
-  }
-}
-```
-
-Output keys: `sequence` (no `loss_mask` — all tokens trained)
-
-### DPO
-
-Input JSONL:
-
-```json
-{"chosen": [{"role": "user", "content": "What is 2+2?"}, {"role": "assistant", "content": "4"}], "rejected": [{"role": "user", "content": "What is 2+2?"}, {"role": "assistant", "content": "5"}]}
-```
-
-Config:
-
-```json
-{
-  "input": {
-    "sources": {
-      "chosen": {
-        "sections": [
-          {"field": "chosen", "action": "$role", "template": true}
-        ]
-      },
-      "rejected": {
-        "sections": [
-          {"field": "rejected", "action": "$role", "template": true}
-        ]
-      }
-    }
-  },
-  "mask": {
-    "user": "mask",
-    "assistant": "train"
-  },
-  "mask_default": "mask"
-}
-```
-
-Output keys: `chosen`, `chosen_mask`, `rejected`, `rejected_mask`
-
-### GRPO
-
-Input JSONL:
-
-```json
-{"prompt": [{"role": "user", "content": "What is 2+2?"}], "responses": ["4", "Five", "Four"], "rewards": [1.0, 0.3, 0.8]}
-```
-
-Config:
-
-```json
-{
-  "input": {
-    "sources": {
-      "prompts": {
-        "sections": [
-          {"field": "prompt", "action": "mask", "template": true}
-        ]
-      },
-      "responses": {
-        "sections": [
-          {"field": "responses", "action": "train"}
-        ],
-        "list_field": true,
-        "mask_key": "masks"
-      },
-      "rewards": {
-        "sections": [
-          {"field": "rewards", "action": "value"}
-        ]
-      }
-    }
-  },
-  "mask": {
-    "user": "mask",
-    "assistant": "train"
-  },
-  "mask_default": "mask"
-}
-```
-
-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
-
---
-
-## Configuration Reference
-
-### `input`
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `sections` | list[dict] or null | `null` | Section specs for single-output mode |
-| `sources` | dict[str, dict] or null | `null` | Source specs for multi-output mode (DPO/GRPO) |
-
-When `sources` is set, `sections` is ignored.
-
-### `mask`
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `mask` | dict | `{}` | `{role: "train" \| "mask"}` |
-| `mask_default` | str | `"mask"` | Default action for unlisted roles |
-
-### `preprocessing`
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `max_seq_len` | int | `2048` | Truncate sequences to this length |
-| `min_chars` | int | `50` | Skip text-mode items shorter than this |
-| `max_chars` | int | `2000000` | Skip text-mode items longer than this |
-| `max_items` | int or null | `null` | Stop after N documents |
-| `packing_strategy` | str | `"simple"` | Packing strategy: `"simple"`, `"bfd"`, `"bfd_split"` |
-| `max_packed_len` | int | `8192` | Maximum length of a packed bin |
-| `truncation_mode` | str | `"keep_start"` | How to truncate sequences: `"keep_start"` or `"keep_end"` |
-
-### `output`
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `domain_key` | str or null | `null` | JSONL key for domain grouping |
-| `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 | `"doc_reset"` | How to compute position_ids: `"none"`, `"doc_reset"`, `"continuous"` |
-
---
-
-## Mask Algorithm
-
-### Template mode (`template: true`)
-
-1. Prepend BOS token (masked)
-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
-
-Encode the field value as text. Mask value is 1 (train) or 0 (mask) per the section's `action`.
-
-### Text config detection
-
-When no section uses `template` and all sections have `action: "train"`, the builder omits `loss_mask` from the output — all tokens are trained.
-
---
-
-## Output Layout
-
-### Single-Shard (`bin`)
-
-```
-output/
-  __default__/
-    shard_0000/
-      meta.json
-      sequence.bin
-      loss_mask.bin
-  wiki/
-    shard_0000/
-      meta.json
-      sequence.bin
-      loss_mask.bin
-```
-
-### Multi-Shard (`bin`)
-
-When `max_tokens_per_shard` is exceeded:
-
-```
-output/
-  __default__/
-    shard_0000/
-      meta.json
-      sequence.bin
-      loss_mask.bin
-    shard_0001/
-      meta.json
-      sequence.bin
-      loss_mask.bin
-```
-
-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.
-
---
-
-## CLI
-
-```bash
-# SFT
-python scripts/tools/preprocess.py data/sft/*.jsonl -o output/sft/ -c configs/sft_chat.json
-
-# DPO
-python scripts/tools/preprocess.py data/dpo/*.jsonl -o output/dpo/ -c configs/dpo.json --tokenizer_path params
-
-# GRPO
-python scripts/tools/preprocess.py data/grpo/*.jsonl -o output/grpo/ -c configs/grpo.json
-```
-
---
-
-## Python API
-
-```python
-from astrai.preprocessing.pipeline import Pipeline
-from astrai.config.preprocess_config import PipelineConfig
-
-config = PipelineConfig.from_file("sft.json")
-Pipeline(
-    config,
-    ["data_part1.jsonl", "data_part2.jsonl"],
-    output_dir="output/",
-    tokenizer_path="params",
-).run()
-```
-
-> Document Update Time: 2026-06-03
@@ -1,17 +1,37 @@
 # Training

-## Contents
+## Model Architecture

- [Autoregression](#autoregression)
- [Causal Mask](#causal-mask)
- [Rotary Position Embedding (RoPE)](#rotary-position-embedding-rope)
- [Training Loop](#training-loop)
- [Strategies](#strategies) — SEQ, SFT, DPO, GRPO
- [LR Schedulers](#lr-schedulers)
- [Gradient Checkpointing](#gradient-checkpointing)
- [Checkpoint](#checkpoint)
- [TrainContextBuilder](#traincontextbuilder-builder-pattern)
- [Training CLI](#training-cli)
+The model uses a decoder-only Transformer with **GQA** (Grouped Query Attention) and optional **MLA** (Multi-head Latent Attention). 1.0 billion parameters, Chinese–English bilingual.
+
+```mermaid
+flowchart TB
+    subgraph Layers["Transformer Layers"]
+        direction TB
+        A[Input Embedding] --> B[Transformer Block\nLayer 1]
+        B --> C[Transformer Block\nLayer ...]
+        C --> D[Transformer Block\nLayer ...]
+        D --> E[RMSNorm]
+        E --> F[Linear]
+        F --> G[SoftMax]
+    end
+
+    subgraph TransformerBlock["Transformer Block"]
+        direction TB
+        H[x] --> I[RMSNorm]
+        I --> J[Linear → Q/K/V]
+        J --> K[Q]; J --> L[K]; J --> M[V]
+        K --> N[RoPE]; L --> O[RoPE]
+        N --> P["Q @ K^T / sqrt(d)"]; O --> P
+        P --> Q[Masked SoftMax]; Q --> R[S @ V]; M --> R
+        R --> S[Linear]; S --> T[+]; H --> T
+        T --> U[RMSNorm]
+        U --> V["Linear (gate)"]; U --> W["Linear (up)"]
+        V --> X[SiLU]; X --> Y[×]; W --> Y
+        Y --> Z["Linear (down)"]; Z --> AA[+]; T --> AA
+        AA --> BB[x']
+    end
+```

 ### Autoregression

@@ -49,26 +69,20 @@ Two-level loop: **epoch** → **batch**. Optimizer step fires every `grad_accum_

 ```
 on_train_begin
-  model.train()
  on_epoch_begin
    for batch in dataloader:
      on_batch_begin
-      with executor.accumulate(model):
-        loss = strategy.compute_loss(batch)
-        context.loss = loss.item()
-        stand_loss = loss / executor.grad_accum_steps
-        executor.backward(stand_loss)
-        context.consumed_samples += (
-            context.config.batch_per_device * context.world_size
-        )
-        on_batch_end
+      loss = strategy(batch)
+      (loss / grad_accum_steps).backward()
+      iteration += 1
+      on_batch_end

-        if executor.sync_gradients:
-          on_optimizer_step
-          optimizer.step()
-          optimizer.zero_grad()
-          if scheduler:
-            scheduler.step()
+      if iteration % grad_accum_steps == 0:
+        on_step_begin
+        optimizer.step()
+        optimizer.zero_grad()
+        on_step_end
+        scheduler.step()
    on_epoch_end
 on_train_end
 ```
@@ -78,15 +92,12 @@ on_train_end
 | Hook | Fires | Default callback |
 |------|-------|-----------------|
 | `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`, `MetricLoggerCallback`, `ValidationCallback` |
+| `on_step_begin` | Every accumulation window | `GradientClippingCallback` |
 | `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` |
+| `on_step_end` | Every accumulation window | `ValidationCallback` |
+| `on_train_end` | Training ends | `CheckpointCallback`, `MetricLoggerCallback` (final save) |

-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`.
+Default callbacks: `gradient_checkpointing` (activation checkpointing, optional), `progress_bar` (tqdm), `checkpoint` (safetensors, rank-0), `metric_logger` (JSONL, rank-0), `gradient_clipping`, `validation` (periodic validation on val_dataset).

 ## Strategies

@@ -98,7 +109,7 @@ $$
 L_{\text{PT}} = -\sum_{t=1}^{T} \log P(x_t \mid x_{\lt t}; \theta)
 $$

-Keys: `input_ids`, `target_ids`. Optional: `label_smoothing`.
+Keys: `input_ids`, `target_ids`

 ### SFT (Supervised Fine-Tuning)

@@ -108,7 +119,7 @@ $$
 L_{\text{SFT}} = -\sum_{t=P+1}^{P+L} \log P(s_t \mid s_{\lt t}; \theta)
 $$

-Keys: `input_ids`, `target_ids`, `loss_mask`. Optional: `label_smoothing`.
+Keys: `input_ids`, `target_ids`, `loss_mask`

 ### DPO (Direct Preference Optimization)

@@ -118,7 +129,7 @@ $$
 L_{\text{DPO}} = -\mathbb{E}\left[\log\sigma\left(\beta\log\frac{\pi_\theta(y_w\mid x)}{\pi_{\text{ref}}(y_w\mid x)} - \beta\log\frac{\pi_\theta(y_l\mid x)}{\pi_{\text{ref}}(y_l\mid x)}\right)\right]
 $$

-Parameters: `beta=0.1`, `reduction="mean"`. Keys: `chosen`, `rejected`, `chosen_mask`, `rejected_mask`.
+Parameters: `beta=0.1`. Keys: `chosen`, `rejected`, `chosen_mask`, `rejected_mask`.

 ### GRPO (Group Relative Policy Optimization)

@@ -132,7 +143,7 @@ $$
 L_{\text{GRPO}} = -\mathbb{E}\left[\min\left(\frac{\pi_\theta}{\pi_{\text{ref}}}A,\; \text{clip}\left(\frac{\pi_\theta}{\pi_{\text{ref}}}, 1-\epsilon, 1+\epsilon\right)A\right)\right] + \lambda \cdot \mathbb{E}\left[(\log\pi_\theta - \log\pi_{\text{ref}})^2\right]
 $$

-Parameters: `group_size=4`, `clip_eps=0.2`, `kl_coef=0.01`, `sync_interval=200`, `reduction="mean"`.
+Parameters: `group_size=4`, `clip_eps=0.2`, `kl_coef=0.01`, `sync_interval=200`.

 Keys: `prompts`, `responses`, `masks`, `rewards`.

@@ -142,9 +153,8 @@ Keys: `prompts`, `responses`, `masks`, `rewards`.
 |------|-------|-------------|
 | Cosine | `CosineScheduler` | Linear warmup → cosine decay to `min_rate` |
 | SGDR | `SGDRScheduler` | Cosine annealing with warm restarts (`t_mult=2`) |
-| WSD | `WSDScheduler` | Warmup-Stable-Decay with sqrt cooldown |

-Created by `SchedulerFactory.create(schedule_type, optimizer, **kwargs)`. Valid types: `"cosine"`, `"sgdr"`, `"wsd"`. Omit to use no scheduler.
+Created by `SchedulerFactory.create(optimizer, schedule_type, **kwargs)`.

 ## Gradient Checkpointing

@@ -160,30 +170,29 @@ Callback wraps each `DecoderBlock.forward` with `torch.utils.checkpoint.checkpoi
 ## Checkpoint

 ```
-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
+Checkpoint(state_dict, epoch, iteration, extra, meta)
+  ├── save(save_dir)    rank-0 only: meta.json (includes training config) + state_dict.safetensors + optional extra.pt
+  └── load(save_dir)    broadcasts metadata from rank-0
 ```

 Optimizer/scheduler state persisted by default via `Checkpoint.extra`.  
-Model config (`context.model_config`) saved into `config.json` during training via `CheckpointCallback`.
+Training config (`TrainConfig.to_dict()`) saved into `meta.json` during training via `CheckpointCallback`.

 ## TrainContextBuilder (Builder Pattern)

 ```python
 context = (
    TrainContextBuilder(config)
-        .with_resume_dir(resume_dir)
+        .with_checkpoint(checkpoint)
        .build()
 )
 # Returns TrainContext with model, strategy, optimizer, scheduler, dataloader, checkpoint
 ```

 - Loads checkpoint weights if provided
- Creates executor via `ExecutorFactory.create(cfg.parallel_mode, grad_accum_steps=cfg.grad_accum_steps, **cfg.executor_kwargs)`
- Calls `executor.prepare(model, optimizer, dataloader, scheduler)` for model distribution (e.g. DDP) + gradient accumulation wrappers
+- Wraps model with `parallel_wrapper` if `nprocs > 1`
 - Creates `ResumableDistributedSampler` for shuffle+resume
- Builds strategy via `StrategyFactory.create(train_type, model, device, **kwargs)`
+- Builds strategy via `StrategyFactory.create(train_type, ...)`

 ## Training CLI

@@ -192,7 +201,6 @@ export CUDA_VISIBLE_DEVICES=0,1,2,3

 nohup python scripts/tools/train.py \
    --nprocs=4 \
-    --parallel_mode=ddp \
    --train_type=seq \
    --data_root_path=/path/to/dataset \
    --param_path=/path/to/model \
@@ -214,4 +222,4 @@ nohup python scripts/tools/train.py \

 Full parameter reference at [params.md](params.md).

-> Document Update Time: 2026-05-30
+> Document Update Time: 2026-05-17
@@ -1,98 +1,34 @@
-__version__ = "1.3.8"
+__version__ = "1.3.5"
 __author__ = "ViperEkura"

 from astrai.config import (
    AutoRegressiveLMConfig,
-    BaseModelConfig,
-    ConfigFactory,
    EncoderConfig,
-    PipelineConfig,
    TrainConfig,
 )
-from astrai.dataset import (
-    BaseDataset,
-    DatasetFactory,
-    ResumableDistributedSampler,
-    Store,
-    StoreFactory,
-)
+from astrai.dataset import DatasetFactory
 from astrai.factory import BaseFactory
 from astrai.inference import (
    GenerationRequest,
    InferenceEngine,
-    ProtocolHandler,
-    SamplingPipeline,
-    get_app,
-    run_server,
-    sample,
-)
-from astrai.model import (
-    AutoModel,
-    AutoRegressiveLM,
-    EmbeddingEncoder,
-    LoRAConfig,
-    inject_lora,
-)
-from astrai.parallel import (
-    ExecutorFactory,
-    get_rank,
-    get_world_size,
-    only_on_rank,
-    spawn_parallel_fn,
-)
-from astrai.preprocessing import Pipeline, filter_by_length
-from astrai.serialization import Checkpoint
-from astrai.tokenize import AutoTokenizer, ChatTemplate
-from astrai.trainer import (
-    BaseScheduler,
-    BaseStrategy,
-    CallbackFactory,
-    SchedulerFactory,
-    StrategyFactory,
-    TrainCallback,
-    Trainer,
 )
+from astrai.model import AutoModel, AutoRegressiveLM
+from astrai.tokenize import AutoTokenizer
+from astrai.trainer import CallbackFactory, SchedulerFactory, StrategyFactory, Trainer

 __all__ = [
    "AutoRegressiveLM",
    "AutoRegressiveLMConfig",
-    "AutoModel",
-    "AutoTokenizer",
-    "BaseDataset",
-    "BaseFactory",
-    "BaseModelConfig",
-    "BaseScheduler",
-    "BaseStrategy",
-    "CallbackFactory",
-    "ChatTemplate",
-    "Checkpoint",
-    "ConfigFactory",
-    "DatasetFactory",
-    "EmbeddingEncoder",
    "EncoderConfig",
-    "ExecutorFactory",
+    "TrainConfig",
+    "DatasetFactory",
+    "AutoTokenizer",
    "GenerationRequest",
    "InferenceEngine",
-    "LoRAConfig",
-    "Pipeline",
-    "PipelineConfig",
-    "ProtocolHandler",
-    "ResumableDistributedSampler",
-    "SamplingPipeline",
-    "SchedulerFactory",
-    "Store",
-    "StoreFactory",
-    "StrategyFactory",
-    "TrainCallback",
-    "TrainConfig",
    "Trainer",
-    "filter_by_length",
-    "get_app",
-    "get_rank",
-    "get_world_size",
-    "inject_lora",
-    "only_on_rank",
-    "run_server",
-    "sample",
-    "spawn_parallel_fn",
+    "CallbackFactory",
+    "StrategyFactory",
+    "SchedulerFactory",
+    "BaseFactory",
+    "AutoModel",
 ]
@@ -4,22 +4,14 @@ from astrai.config.model_config import (
    ConfigFactory,
    EncoderConfig,
 )
-from astrai.config.preprocess_config import (
-    InputConfig,
-    OutputConfig,
-    PipelineConfig,
-    ProcessingConfig,
-)
 from astrai.config.train_config import TrainConfig

 __all__ = [
+    # Model configuration
    "BaseModelConfig",
    "AutoRegressiveLMConfig",
    "EncoderConfig",
+    "ModelConfig",
    "ConfigFactory",
    "TrainConfig",
-    "InputConfig",
-    "OutputConfig",
-    "PipelineConfig",
-    "ProcessingConfig",
 ]
@@ -1,7 +1,6 @@
 import json
 from dataclasses import MISSING, dataclass, fields
-from pathlib import Path
-from typing import Any, Dict, Optional, Self, Union, get_type_hints
+from typing import Any, Dict, Optional, Self, get_type_hints


@dataclass
@@ -14,21 +13,12 @@ class BaseConfig:
                d[fld.name] = v
            elif v is None:
                d[fld.name] = None
-            elif isinstance(v, (dict, list, tuple)):
+            elif isinstance(v, dict):
                try:
-                    val = list(v) if isinstance(v, tuple) else v
-                    json.dumps(val)
-                    d[fld.name] = val
+                    json.dumps(v)
+                    d[fld.name] = v
                except (TypeError, ValueError):
                    pass
-            elif isinstance(v, BaseConfig):
-                d[fld.name] = v.to_dict()
-            elif hasattr(v, "__dataclass_fields__"):
-                sub = {}
-                for f in fields(v):
-                    a = getattr(v, f.name)
-                    sub[f.name] = list(a) if isinstance(a, tuple) else a
-                d[fld.name] = sub
        return d

    @classmethod
@@ -84,15 +74,4 @@ class BaseConfig:
            return value
        if isinstance(value, target_type):
            return value
-        if isinstance(value, dict) and issubclass(target_type, BaseConfig):
-            return target_type.from_dict(value)
        raise TypeError
-
-    @classmethod
-    def from_file(cls, path: Union[str, Path]) -> Self:
-        with open(path, "r", encoding="utf-8") as f:
-            return cls.from_dict(json.load(f))
-
-    def to_file(self, path: Union[str, Path]):
-        with open(path, "w", encoding="utf-8") as f:
-            json.dump(self.to_dict(), f, indent=2, ensure_ascii=False)
@@ -1,5 +1,6 @@
+import json
 from dataclasses import dataclass
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Self

 from astrai.config.base import BaseConfig
 from astrai.factory import BaseFactory
@@ -20,7 +21,18 @@ class BaseModelConfig(BaseConfig):
    """Base config with ``model_type`` dispatch and file I/O."""

    model_type: Optional[str] = None
-    neftune_alpha: float = 0.0
+
+    @classmethod
+    def from_file(cls, config_path: str) -> Self:
+        with open(config_path, "r") as f:
+            raw: Dict[str, Any] = json.load(f)
+        return cls.from_dict(raw)
+
+    def to_file(self, config_path: str):
+        d = self.to_dict()
+        config_dict = {k: v for k, v in d.items() if v is not None}
+        with open(config_path, "w") as f:
+            json.dump(config_dict, f, indent=4)


@dataclass
@@ -37,7 +49,6 @@ class AutoRegressiveLMConfig(BaseModelConfig):

    max_len: Optional[int] = None
    rope_theta: Optional[float] = None
-    rope_scaling: Optional[dict] = None

    attn_type: str = "gqa"
    n_heads: Optional[int] = None
@@ -69,14 +80,11 @@ class EncoderConfig(BaseModelConfig):

    max_len: Optional[int] = None
    rope_theta: Optional[float] = None
-    rope_scaling: Optional[dict] = None

-    attn_type: str = "gqa"
    n_heads: Optional[int] = None
    n_kv_heads: Optional[int] = None
    use_qk_norm: Optional[bool] = None
    use_gated_attention: Optional[bool] = None

-    ffn_type: str = "mlp"
    pooling_type: Optional[str] = None
    normalize_embeddings: Optional[bool] = None
@@ -1,109 +0,0 @@
-"""Pipeline configuration for JSONL preprocessing.
-
-Supports single-sequence (SFT/pretrain) and multi-output (DPO/GRPO)
-modes, both driven declaratively through ``input.sections`` or
-``input.sources``.
-"""
-
-from dataclasses import dataclass, field
-from typing import Dict, List, Optional
-
-from astrai.config.base import BaseConfig
-
-
-@dataclass
-class InputConfig(BaseConfig):
-    """Declarative input mapping.
-
-    Single-output mode (backward-compatible)::
-
-        {"input": {"sections": [{"field": "messages", ...}]}}
-
-    Multi-output mode (DPO / GRPO)::
-
-        {"input": {"sources": {
-            "chosen": {"sections": [{"field": "chosen", ...}]},
-            "rejected": {"sections": [{"field": "rejected", ...}]},
-        }}}
-    """
-
-    sections: Optional[List[Dict]] = None
-    sources: Optional[Dict[str, Dict]] = None
-
-
-@dataclass
-class ProcessingConfig(BaseConfig):
-    """Processing configuration.
-
-    Parameters
-    ----------
-    max_seq_len : int
-        Maximum sequence length (default: 2048).
-    min_chars : int
-        Minimum number of characters to keep (default: 50).
-    max_chars : int
-        Maximum number of characters to keep (default: 2_000_000).
-    max_items : Optional[int]
-        Maximum number of items to process (default: None, unlimited).
-    packing_strategy : str
-        How to pack sequences into a contiguous stream.
-
-        - ``"simple"``: sequential concatenation (default, backward compatible).
-        - ``"bfd"``: best-fit decreasing bin packing, minimises wasted tokens.
-        - ``"bfd_split"``: BFD with over-length sequences split into chunks.
-    max_packed_len : int
-        Maximum length of a packed bin. Sequences longer than this are
-        truncated or split depending on ``packing_strategy`` (default: 8192).
-    truncation_mode : str
-        How to truncate sequences longer than ``max_packed_len``.
-
-        - ``"keep_start"``: keep the first ``max_packed_len`` tokens (default).
-        - ``"keep_end"``: keep the last ``max_packed_len`` tokens.
-    """
-
-    max_seq_len: int = 2048
-    min_chars: int = 50
-    max_chars: int = 2_000_000
-    max_items: Optional[int] = None
-    packing_strategy: str = "simple"
-    max_packed_len: int = 8192
-    truncation_mode: str = "keep_start"
-
-
-@dataclass
-class OutputConfig(BaseConfig):
-    """Output configuration.
-
-    Parameters
-    ----------
-    domain_key : Optional[str]
-        Domain key for the output store (default: None).
-    storage_format : str
-        Storage format, one of ``"bin"``, ``"jsonl"`` (default: ``"bin"``).
-    max_tokens_per_shard : int
-        Maximum tokens per shard before splitting (default: 100_000_000).
-    dtype : Dict[str, str]
-        Per-key dtype overrides, e.g. ``{"input_ids": "int32"}`` (default: {}).
-    position_ids_mode : Optional[str]
-        How to compute position_ids in packed sequences.
-
-         - ``"none"``: do not generate (default).
-        - ``"doc_reset"``: reset to 0 at each document boundary.
-        - ``"continuous"``: sequential 0, 1, 2, ... (pretrain, single doc).
-    """
-
-    domain_key: Optional[str] = None
-    storage_format: str = "bin"
-    max_tokens_per_shard: int = 100_000_000
-    dtype: Dict[str, str] = field(default_factory=dict)
-    position_ids_mode: str = "doc_reset"
-
-
-@dataclass
-class PipelineConfig(BaseConfig):
-    version: int = 1
-    input: InputConfig = field(default_factory=InputConfig)
-    mask: Dict[str, str] = field(default_factory=dict)
-    mask_default: str = "mask"
-    preprocessing: ProcessingConfig = field(default_factory=ProcessingConfig)
-    output: OutputConfig = field(default_factory=OutputConfig)
@@ -1,5 +1,5 @@
 from dataclasses import dataclass, field, fields
-from typing import Any, Callable, Dict, List, Optional
+from typing import Callable, Optional

 import torch.nn as nn
 from torch.optim import Optimizer
@@ -7,7 +7,6 @@ from torch.optim.lr_scheduler import LRScheduler
 from torch.utils.data import Dataset

 from astrai.config.base import BaseConfig
-from astrai.model.components.lora import LoRAConfig


 def required(**kw):
@@ -17,8 +16,8 @@ def required(**kw):
@dataclass
 class TrainConfig(BaseConfig):
    # basic setting
-    model_fn: Callable[[], nn.Module] = field(
-        default=None, metadata=required(help="Model factory for training.")
+    model: nn.Module = field(
+        default=None, metadata=required(help="Model for training.")
    )
    strategy: str = field(default=None, metadata=required(help="Training strategy."))
    dataset: Dataset = field(
@@ -40,40 +39,21 @@ class TrainConfig(BaseConfig):
    max_grad_norm: float = field(
        default=1.0, metadata={"help": "Maximum gradient norm."}
    )
-    gradient_checkpointing_modules: List[str] = field(
+    gradient_checkpointing_modules: list = field(
        default_factory=list,
        metadata={"help": "Module types to enable activation checkpointing for."},
    )

    # checkpoint setting
    start_epoch: int = field(default=0, metadata={"help": "Start epoch for training."})
-    start_samples: int = field(
-        default=0,
-        metadata={
-            "help": "Start samples count (per rank). Superseded by checkpoint consumed_samples."
-        },
+    start_batch: int = field(
+        default=0, metadata={"help": "Start batch iteration for training."}
    )
    ckpt_dir: str = field(
        default="./checkpoint", metadata={"help": "Checkpoint directory."}
    )
    ckpt_interval: int = field(
-        default=5000,
-        metadata={"help": "Number of optimizer steps between checkpoints."},
-    )
-
-    # lora setting
-    lora: Optional[LoRAConfig] = field(
-        default=None,
-        metadata={"help": "LoRA config. None means full fine-tuning."},
-    )
-
-    # metric setting
-    log_dir: str = field(
-        default="./checkpoint/logs", metadata={"help": "Directory for metric logs."}
-    )
-    metrics: List[str] = field(
-        default_factory=lambda: ["loss", "lr", "grad_norm"],
-        metadata={"help": "Metrics to record during training."},
+        default=5000, metadata={"help": "Number of iterations between checkpoints."}
    )

    # dataloader setting
@@ -102,9 +82,11 @@ class TrainConfig(BaseConfig):
    master_port: str = field(
        default="29500", metadata={"help": "Master port for distributed training."}
    )
-    parallel_mode: str = field(
-        default="none",
-        metadata={"help": "Parallel strategy: none, ddp, fsdp."},
+    parallel_wrapper: Optional[Callable] = field(
+        default=None, metadata={"help": "Parallel function for training."}
+    )
+    state_dict_fn: Optional[Callable] = field(
+        default=None, metadata={"help": "Parallel function for state  dict saving."}
    )
    start_method: str = field(
        default="spawn",
@@ -118,26 +100,12 @@ class TrainConfig(BaseConfig):
    val_dataset: Optional[Dataset] = field(
        default=None, metadata={"help": "Dataset for validation."}
    )
-    val_split: Optional[float] = field(
-        default=None,
-        metadata={
-            "help": "Ratio to split from training dataset for validation (e.g. 0.05). Ignored if val_dataset is set."
-        },
-    )
    val_step: int = field(
        default=1000,
        metadata={"help": "Number of optimizer steps between validation runs."},
    )
-    neftune_alpha: float = field(
-        default=0.0,
-        metadata={"help": "NEFTune noise alpha (0=disabled, typical: 5.0)."},
-    )

-    executor_kwargs: Dict[str, Any] = field(
-        default_factory=dict,
-        metadata={"help": "Extra kwargs passed to ExecutorFactory.create()."},
-    )
-    extra_kwargs: Dict[str, Any] = field(
+    extra_kwargs: dict = field(
        default_factory=dict, metadata={"help": "Other arguments."}
    )

@@ -4,32 +4,32 @@ from astrai.dataset.dataset import (
 )
 from astrai.dataset.sampler import ResumableDistributedSampler
 from astrai.dataset.storage import (
-    H5Store,
-    JsonlStore,
-    MmapStore,
-    Store,
-    StoreFactory,
+    BaseSegmentFetcher,
+    BaseStorage,
+    H5Storage,
+    JSONStorage,
+    MultiSegmentFetcher,
+    StorageFactory,
    detect_format,
-)
-from astrai.serialization import (
-    load_bin,
    load_h5,
-    save_bin,
+    load_json,
    save_h5,
+    save_json,
 )

 __all__ = [
    "BaseDataset",
    "DatasetFactory",
-    "Store",
-    "StoreFactory",
-    "H5Store",
-    "MmapStore",
-    "JsonlStore",
+    "BaseSegmentFetcher",
+    "MultiSegmentFetcher",
+    "BaseStorage",
+    "H5Storage",
+    "JSONStorage",
+    "StorageFactory",
    "detect_format",
    "save_h5",
    "load_h5",
-    "save_bin",
-    "load_bin",
+    "save_json",
+    "load_json",
    "ResumableDistributedSampler",
 ]
@@ -8,8 +8,8 @@ from torch import Tensor
 from torch.utils.data import Dataset

 from astrai.dataset.storage import (
-    Store,
-    StoreFactory,
+    BaseStorage,
+    StorageFactory,
    detect_format,
 )
 from astrai.factory import BaseFactory
@@ -26,7 +26,7 @@ class BaseDataset(Dataset, ABC):
        super().__init__()
        self.window_size = window_size
        self.stride = stride
-        self.storage: Optional[Store] = None
+        self.storage: Optional[BaseStorage] = None

    @property
    def required_keys(self) -> List[str]:
@@ -48,28 +48,37 @@ class BaseDataset(Dataset, ABC):
                f"Missing: {missing}"
            )

-    def load(self, load_path: str, storage_type: Optional[str] = None, **kwargs):
+    def load(self, load_path: str, storage_type: Optional[str] = None, tokenizer=None):
        """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", "jsonl"),
+            storage_type: Force a specific storage type ("h5", "json"),
                          or None for auto-detection
-            **kwargs: Extra arguments forwarded to the store constructor and
-                      to ``store.load()``.
+            tokenizer: Callable str -> List[int], used to tokenize raw text
+                       in JSON files. Ignored for HDF5.

        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, **kwargs)
+        self.storage = StorageFactory.create(storage_type)
        self._load_path = load_path
-        self.storage.load(load_path, **kwargs)
+        self.storage.load(load_path, tokenizer=tokenizer)
        self._validate_keys()

+    def load_json(self, load_path: str, tokenizer=None):
+        """Load dataset from JSON files explicitly.
+
+        Args:
+            load_path: Path to the JSON data file or directory
+            tokenizer: Optional tokenizer callable for raw text JSON.
+        """
+        self.load(load_path, storage_type="json", tokenizer=tokenizer)
+
    @property
    def count(self) -> int:
        """Return the total number of raw elements (tokens) in the dataset."""
@@ -138,6 +147,26 @@ class DatasetFactory(BaseFactory["BaseDataset"]):
        dataset = DatasetFactory.create("custom", window_size, stride)
    """

+    @classmethod
+    def _validate_component(cls, dataset_cls: type) -> None:
+        """Validate that the dataset class inherits from BaseDataset."""
+        if not issubclass(dataset_cls, BaseDataset):
+            raise TypeError(f"{dataset_cls.__name__} must inherit from BaseDataset")
+
+    @classmethod
+    def create(cls, train_type: str, window_size: int, stride: int) -> "BaseDataset":
+        """Create a dataset instance.
+
+        Args:
+            train_type: Type of training ("seq", "sft", "dpo", "grpo")
+            window_size: Window size for data sampling
+            stride: Stride between consecutive samples
+
+        Returns:
+            Dataset instance
+        """
+        return super().create(train_type, window_size, stride)
+
    @classmethod
    def load(
        cls,
@@ -146,7 +175,7 @@ class DatasetFactory(BaseFactory["BaseDataset"]):
        window_size: int,
        stride: Optional[int] = None,
        storage_type: Optional[str] = None,
-        **kwargs,
+        tokenizer=None,
    ) -> "BaseDataset":
        """Create and load a dataset in one step.

@@ -155,8 +184,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", "jsonl") or None for auto-detection
-            **kwargs: Extra arguments forwarded to ``dataset.load()``.
+            storage_type: Storage type ("h5", "json") or None for auto-detection
+            tokenizer: Callable str -> List[int] for raw text JSON tokenization

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

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

        return dataset

+    @classmethod
+    def available_types(cls) -> list:
+        """Return list of registered dataset type names."""
+        return cls.list_registered()
+

@DatasetFactory.register("seq")
 class SEQDataset(BaseDataset):
    """Dataset for sequential next-token prediction training."""

+    def __init__(self, window_size: int, stride: int):
+        super().__init__(window_size, stride)
+
    @property
    def required_keys(self) -> List[str]:
        return ["sequence"]
@@ -194,9 +231,12 @@ class SEQDataset(BaseDataset):
 class SFTDataset(BaseDataset):
    """Dataset for supervised fine-tuning with loss masking."""

+    def __init__(self, window_size: int, stride: int):
+        super().__init__(window_size, stride)
+
    @property
    def required_keys(self) -> List[str]:
-        return ["sequence", "loss_mask", "position_ids"]
+        return ["sequence", "loss_mask"]

    def _fetch_data(self, begin_idx: int, end_idx: int, key: str) -> Tensor:
        return self.storage.fetch(begin_idx, end_idx, key)
@@ -204,23 +244,24 @@ class SFTDataset(BaseDataset):
    def __getitem__(self, index):
        begin_idx, end_idx = self.get_index(index)

-        x = self._fetch_data(begin_idx, end_idx, "sequence")
-        y = self._fetch_data(begin_idx + 1, end_idx + 1, "sequence")
-        position_ids = self._fetch_data(begin_idx, end_idx, "position_ids")
-        loss_mask = self._fetch_data(begin_idx + 1, end_idx + 1, "loss_mask")
+        x = self._fetch_data(begin_idx, end_idx, "sequence").to(dtype=torch.long)
+        y = self._fetch_data(begin_idx + 1, end_idx + 1, "sequence").to(
+            dtype=torch.long
+        )
+        loss_mask = self._fetch_data(begin_idx + 1, end_idx + 1, "loss_mask").to(
+            dtype=torch.bool
+        )

-        return {
-            "input_ids": x.to(dtype=torch.long),
-            "target_ids": y.to(dtype=torch.long),
-            "position_ids": position_ids.to(dtype=torch.long),
-            "loss_mask": loss_mask.to(dtype=torch.bool),
-        }
+        return {"input_ids": x, "target_ids": y, "loss_mask": loss_mask}


@DatasetFactory.register("dpo")
 class DPODataset(BaseDataset):
    """Dataset for Direct Preference Optimization training."""

+    def __init__(self, window_size: int, stride: int):
+        super().__init__(window_size, stride)
+
    @property
    def required_keys(self) -> List[str]:
        return ["chosen", "rejected", "chosen_mask", "rejected_mask"]
@@ -252,6 +293,9 @@ class DPODataset(BaseDataset):
 class GRPODataset(BaseDataset):
    """Dataset for Group Relative Policy Optimization training."""

+    def __init__(self, window_size: int, stride: int):
+        super().__init__(window_size, stride)
+
    @property
    def required_keys(self) -> List[str]:
        return ["prompts", "responses", "masks", "rewards"]
@@ -262,11 +306,9 @@ class GRPODataset(BaseDataset):
    def __getitem__(self, index: int) -> Dict[str, Tensor]:
        begin_idx, end_idx = self.get_index(index)

-        prompts = self._fetch_data(begin_idx, end_idx, "prompts").to(dtype=torch.long)
-        responses = self._fetch_data(begin_idx, end_idx, "responses").to(
-            dtype=torch.long
-        )
-        masks = self._fetch_data(begin_idx, end_idx, "masks").to(dtype=torch.bool)
+        prompts = self._fetch_data(begin_idx, end_idx, "prompts")
+        responses = self._fetch_data(begin_idx, end_idx, "responses")
+        masks = self._fetch_data(begin_idx, end_idx, "masks")
        rewards = self._fetch_data(begin_idx, end_idx, "rewards")

        return {
@@ -43,7 +43,6 @@ class ResumableDistributedSampler(Sampler[int]):
        offset = 0 if drop_last else self.num_replicas - 1
        self.num_samples_per_replica = (self.num_samples + offset) // self.num_replicas
        self.total_size = self.num_samples_per_replica * self.num_replicas
-        self.iter = self.iter % self.num_samples_per_replica

        self._indices = None

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

        self.epoch += 1
        self._indices = None
-        self.iter = self.iter % self.num_samples_per_replica
-
-    @property
-    def _remaining(self):
-        remaining = self.num_samples_per_replica - self.iter
-        return max(remaining, 0)

    def __len__(self):
-        return self._remaining
+        return self.num_samples_per_replica
@@ -1,44 +1,107 @@
 """Storage backends for different data formats.

-Layers:
-  - I/O layer:       save_* / load_* functions, read/write raw files (HDF5/bin)
-                      return Dict[str, List[Tensor]] — format-specific, no state
-  - Store (ABC):     central abstraction, normalizes multi-segment into
-                      Dict[str, List[Tensor]] per key via _normalize(),
-                      fetch() uses bisect across segments — no forced concat
-  - Dataset layer:   BaseDataset owns a Store, only calls store.fetch(begin, end, key)
-
-Key properties:
-  - Multi-segment:   segments kept as-is, no forced concatenation — safe for
-                      datasets larger than RAM
-  - 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
+Each storage handles format-specific loading (HDF5, JSON, etc.) and provides
+a uniform interface for data access and length observation via fetchers.
 """

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

+import h5py
 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

-logger = logging.getLogger(__name__)
+
+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_json(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}.json")
+    json_data = {}
+    for key, tensors in tensor_group.items():
+        json_data[key] = [tensor.tolist() for tensor in tensors]
+    with open(full_file_path, "w", encoding="utf-8") as f:
+        json.dump(json_data, f, ensure_ascii=False)
+
+
+def load_json(
+    file_path: str,
+    share_memory: bool = True,
+    tokenizer: Optional[Callable[[str], List[int]]] = None,
+) -> Dict[str, List[Tensor]]:
+    """Load tensor data from JSON files.
+
+    Supports two modes:
+    - Pre-tokenized: JSON values are List[List[int]] (token IDs), loaded as-is.
+    - Raw text: JSON values are List[str], tokenized via ``tokenizer`` callable
+      at load time. A ``tokenizer`` receives a str and returns List[int].
+
+    Non-data JSON files (e.g. config.json) with scalar/object values are
+    silently skipped.
+    """
+    tensor_group: Dict[str, List[Tensor]] = {}
+    root_path = Path(file_path)
+    json_files = list(root_path.rglob("*.json")) + list(root_path.rglob("*.jsonl"))
+    for json_file in json_files:
+        with open(json_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            continue
+        for key, sequences in data.items():
+            if not isinstance(sequences, list):
+                continue
+            tensors = []
+            for seq in sequences:
+                if tokenizer is not None and isinstance(seq, str):
+                    seq = tokenizer(seq)
+                tensor = torch.tensor(seq, dtype=torch.long)
+                if share_memory:
+                    tensor = tensor.share_memory_()
+                tensors.append(tensor)
+            if tensor_group.get(key) is None:
+                tensor_group[key] = []
+            tensor_group[key].extend(tensors)
+    return tensor_group


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

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

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

-    h5_files = [
-        Path(p)
-        for pattern in ("*.h5", "*.hdf5")
-        for p in glob.glob(str(root / "**" / pattern), recursive=True)
-    ]
+    h5_files = list(root.rglob("*.h5")) + list(root.rglob("*.hdf5"))
    if h5_files:
        return "h5"
-    bin_files = [Path(p) for p in glob.glob(str(root / "**" / "*.bin"), recursive=True)]
-    if bin_files:
-        has_meta = (root / "meta.json").exists() or len(
-            [Path(p) for p in glob.glob(str(root / "**" / "meta.json"), recursive=True)]
-        ) > 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"
+    json_files = list(root.rglob("*.json")) + list(root.rglob("*.jsonl"))
+    if json_files:
+        return "json"
    raise FileNotFoundError(f"No supported data files found at {load_path}")


-class Store(ABC):
-    """String keys -> segmented tensors with ``fetch(begin, end, keys)``.
+class BaseSegmentFetcher:
+    """Fetches data segments across multiple tensor segments.

-    Each key maps to one or more tensor segments (no forced concatenation).
-    ``len(store)`` returns ``self._length`` (explicit, O(1)), the minimum
-    total element count across all keys.
+    Maintains cumulative lengths for efficient range queries across
+    multiple discontinuous segments.
+    """

-    Subclasses fill ``self._data`` and ``self._cum`` during ``load()``
-    via ``_normalize()``.
+    def __init__(self, segments: List[Tensor]):
+        self.segments = segments
+        self.cum_lengths = []
+
+        total = 0
+        for seg in segments:
+            total += torch.numel(seg)
+            self.cum_lengths.append(total)
+
+        self.total_length = total
+
+    def __len__(self) -> int:
+        return self.total_length
+
+    def fetch_data(self, begin_idx: int, end_idx: int) -> Tensor:
+        """Fetch data in the range [begin_idx, end_idx)."""
+        if not (
+            0 <= begin_idx < self.total_length and 0 <= end_idx <= self.total_length
+        ):
+            raise ValueError("begin_idx or end_idx out of bounds")
+        if begin_idx >= end_idx:
+            return torch.tensor([], dtype=torch.long)
+
+        seg_start_idx = bisect.bisect_right(self.cum_lengths, begin_idx)
+        seg_end_idx = bisect.bisect_left(self.cum_lengths, end_idx)
+
+        result_segments = []
+
+        for i in range(seg_start_idx, seg_end_idx + 1):
+            prev_cum = self.cum_lengths[i - 1] if i > 0 else 0
+            start = max(begin_idx - prev_cum, 0)
+            end = min(end_idx - prev_cum, len(self.segments[i]))
+            result_segments.append(self.segments[i][start:end])
+
+        return torch.cat(result_segments, dim=0)
+
+
+class MultiSegmentFetcher:
+    """Manages multiple segment fetchers for different data keys."""
+
+    def __init__(self, multi_segments: Dict):
+        self.multi_keys = list(multi_segments.keys())
+        self.multi_fetchers = {
+            key: BaseSegmentFetcher(segments)
+            for key, segments in multi_segments.items()
+        }
+
+    def __len__(self) -> int:
+        """Returns the minimum length across all fetchers."""
+        if not self.multi_fetchers:
+            return 0
+        len_list = [len(seg) for seg in self.multi_fetchers.values()]
+        return min(len_list)
+
+    def key_fetch(
+        self, begin_idx: int, end_idx: int, keys: Union[str, List[str]]
+    ) -> Dict:
+        """Fetch data for specific keys."""
+        fetch_dict = {}
+        keys = [keys] if isinstance(keys, str) else keys
+
+        for key in keys:
+            fetcher = self.multi_fetchers[key]
+            fetch_tensor = fetcher.fetch_data(begin_idx, end_idx)
+            fetch_dict[key] = fetch_tensor
+
+        return fetch_dict if len(keys) > 1 else fetch_dict[keys[0]]
+
+    def fetch_data(self, begin_idx: int, end_idx: int) -> Dict:
+        """Fetch all keys."""
+        return self.key_fetch(begin_idx, end_idx, self.multi_keys)
+
+
+class BaseStorage(ABC):
+    """Abstract storage backend for loading and dispatching data.
+
+    Storage encapsulates format-specific loading and provides a uniform
+    interface for data access and length observation. Subclasses handle
+    different data formats (HDF5, JSON, etc.) while exposing the same
+    fetch interface.
    """

    def __init__(self):
-        self._data: Dict[str, List[Tensor]] = {}
-        self._cum: Dict[str, List[int]] = {}
-        self._length: int = 0
+        self._fetcher: Optional[MultiSegmentFetcher] = None

    @abstractmethod
-    def load(self, path: str) -> None:
+    def load(self, load_path: str, tokenizer=None) -> None:
+        """Load data from the given path into internal fetcher."""
        raise NotImplementedError

+    def __len__(self) -> int:
+        """Total number of raw elements (tokens) in storage."""
+        if self._fetcher is None:
+            return 0
+        return len(self._fetcher)
+
+    def fetch(self, begin_idx: int, end_idx: int, keys: Union[str, List[str]]):
+        """Fetch data for the given keys and index range.
+
+        Args:
+            begin_idx: Starting index (inclusive)
+            end_idx: Ending index (exclusive)
+            keys: Single key or list of keys to fetch
+
+        Returns:
+            Tensor if single key, Dict[str, Tensor] if multiple keys
+        """
+        if self._fetcher is None:
+            raise RuntimeError("Storage not loaded")
+        return self._fetcher.key_fetch(begin_idx, end_idx, keys)
+
    @property
    def keys(self) -> List[str]:
-        return list(self._data.keys())
-
-    def __len__(self) -> int:
-        return self._length
-
-    def fetch(
-        self,
-        begin: int,
-        end: int,
-        keys: Union[str, List[str]],
-    ):
-        if not self._data:
-            raise RuntimeError("Store not loaded")
-        if not (0 <= begin < self._length and 0 <= end <= self._length):
-            raise ValueError(
-                f"Index out of bounds: begin={begin}, end={end}, length={self._length}"
-            )
-        if isinstance(keys, str):
-            return self._fetch_key(keys, begin, end)
-        return {k: self._fetch_key(k, begin, end) for k in keys}
-
-    def _fetch_key(self, key: str, begin: int, end: int) -> Tensor:
-        """Fetch slice [begin, end) across potentially multiple segments."""
-        segments = self._data[key]
-        cum = self._cum[key]
-        seg_start = bisect.bisect_right(cum, begin)
-        seg_end = bisect.bisect_left(cum, end)
-
-        results = []
-        for i in range(seg_start, seg_end + 1):
-            prev = cum[i - 1] if i > 0 else 0
-            s = max(begin - prev, 0)
-            e = min(end - prev, segments[i].shape[0])
-            results.append(segments[i][s:e])
-
-        return results[0] if len(results) == 1 else torch.cat(results, dim=0)
-
-    def _normalize(self, raw: Dict[str, List[Tensor]]):
-        """Register segments and pre-compute cumulative lengths.
-
-        Does NOT concatenate — segments are kept as-is to avoid OOM on
-        large datasets.  Sets ``self._length`` to the minimum total
-        element count across all keys.
-        """
-        for key, tensors in raw.items():
-            self._data[key] = tensors
-            cum = []
-            total = 0
-            for t in tensors:
-                total += t.shape[0]
-                cum.append(total)
-            self._cum[key] = cum
-        self._length = (
-            min((cum[-1] if cum else 0) for cum in self._cum.values())
-            if self._cum
-            else 0
-        )
+        """Return the data keys available in this storage."""
+        if self._fetcher is None:
+            return []
+        return self._fetcher.multi_keys


-class StoreFactory(BaseFactory["Store"]):
-    """Factory for creating Store instances by type name.
+class StorageFactory(BaseFactory["BaseStorage"]):
+    """Factory for creating storage backends by type name.

-    Example::
-
-        @StoreFactory.register("custom")
-        class CustomStore(Store):
+    Example:
+        @StorageFactory.register("custom")
+        class CustomStorage(BaseStorage):
            ...
+
+        storage = StorageFactory.create("custom")
    """

+    @classmethod
+    def _validate_component(cls, storage_cls: type) -> None:
+        if not issubclass(storage_cls, BaseStorage):
+            raise TypeError(f"{storage_cls.__name__} must inherit from BaseStorage")

-@StoreFactory.register("h5")
-class H5Store(Store):
+
+@StorageFactory.register("h5")
+class H5Storage(BaseStorage):
    """HDF5-based storage backend (pre-tokenized data)."""

-    def load(self, path: str):
-        self._normalize(load_h5(path))
+    def load(self, load_path: str, tokenizer=None) -> None:
+        segments = load_h5(load_path)
+        self._fetcher = MultiSegmentFetcher(segments)


-@StoreFactory.register("bin")
-class MmapStore(Store):
-    """Memory-mapped binary storage backend.
+@StorageFactory.register("json")
+class JSONStorage(BaseStorage):
+    """JSON-based storage backend.

-    Each key is a single .bin file backed by ``np.memmap(mode="r")``.
-    No per-process memory duplication — all DataLoader workers share the
-    same OS page-cache pages.
-
-    Format on disk::
-
-        data_root/
-          meta.json          # {key: {shape, dtype}, ...}
-          <key>.bin          # raw numpy array, one per key
+    Supports two modes:
+    - Pre-tokenized: JSON values are List[List[int]], loaded as-is.
+    - Raw text: JSON values are List[str], tokenized via ``tokenizer``
+      callable (str -> List[int]) at load time.
    """

-    def load(self, path: str):
-        self._mmap_refs = []
-        root = Path(path)
-        all_raw: Dict[str, List[Tensor]] = {}
-        meta_paths = [
-            Path(p) for p in glob.glob(str(root / "**" / "meta.json"), recursive=True)
-        ]
-        for meta_path in meta_paths:
-            raw = load_bin(str(meta_path.parent))
-            for key, tensors in raw.items():
-                if key not in all_raw:
-                    all_raw[key] = []
-                all_raw[key].extend(tensors)
-        if not meta_paths:
-            raise FileNotFoundError(f"No meta.json found under {path}")
-        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
+    def load(self, load_path: str, tokenizer=None) -> None:
+        segments = load_json(load_path, tokenizer=tokenizer)
+        self._fetcher = MultiSegmentFetcher(segments)
@@ -1,103 +1,149 @@
-"""Base factory with decorator-based registration and kwarg-filtered instantiation."""
+"""Base factory class for extensible component registration."""

 import inspect
-import sys
 from abc import ABC
-from typing import (
-    Callable,
-    Dict,
-    ForwardRef,
-    Generic,
-    List,
-    Optional,
-    Type,
-    TypeVar,
-    Union,
-)
-from typing import get_args as _get_args
-from typing import get_origin as _get_origin
+from typing import Callable, Dict, Generic, List, Optional, Tuple, Type, TypeVar

 T = TypeVar("T")


-def _resolve_type(
-    arg: Union[Type, str, ForwardRef], factory_cls: type
-) -> Optional[Type]:
-    """Resolve a generic type-arg (str forward-ref, ForwardRef, or class)."""
-    if not isinstance(arg, (str, ForwardRef)):
-        return arg
+class Registry:
+    """Flexible registry for component classes with category and priority support.

-    name = arg if isinstance(arg, str) else arg.__forward_arg__
-    if name == factory_cls.__name__:
-        return factory_cls
+    This registry stores component classes with optional metadata (category, priority).
+    It provides methods for registration, retrieval, and listing with filtering.
+    """

-    mod = sys.modules.get(factory_cls.__module__)
-    if mod is None:
-        return None
-    ns = vars(mod)
+    def __init__(self):
+        self._entries = {}  # name -> (component_cls, category, priority)

-    if isinstance(arg, ForwardRef):
-        return arg._evaluate(ns, None, recursive_guard=frozenset())
+    def register(
+        self,
+        name: str,
+        component_cls: Type,
+        category: Optional[str] = None,
+        priority: int = 0,
+    ) -> None:
+        """Register a component class with optional category and priority."""
+        if name in self._entries:
+            raise ValueError(f"Component '{name}' is already registered")
+        self._entries[name] = (component_cls, category, priority)

-    return ns.get(name)
+    def get(self, name: str) -> Type:
+        """Get component class by name."""
+        if name not in self._entries:
+            raise KeyError(f"Component '{name}' not found in registry")
+        return self._entries[name][0]
+
+    def get_with_metadata(self, name: str) -> Tuple[Type, Optional[str], int]:
+        """Get component class with its metadata."""
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(f"Component '{name}' not found in registry")
+        return entry
+
+    def contains(self, name: str) -> bool:
+        """Check if a name is registered."""
+        return name in self._entries
+
+    def list_names(self) -> List[str]:
+        """Return list of registered component names."""
+        return sorted(self._entries.keys())
+
+    def list_by_category(self, category: str) -> List[str]:
+        """Return names of components belonging to a specific category."""
+        return sorted(
+            name for name, (_, cat, _) in self._entries.items() if cat == category
+        )
+
+    def list_by_priority(self, reverse: bool = False) -> List[str]:
+        """Return names sorted by priority (default ascending)."""
+        return sorted(
+            self._entries.keys(),
+            key=lambda name: self._entries[name][2],
+            reverse=reverse,
+        )
+
+    def entries(self) -> Dict[str, Tuple[Type, Optional[str], int]]:
+        """Return raw entries dictionary."""
+        return self._entries.copy()


 class BaseFactory(ABC, Generic[T]):
-    """Generic factory with decorator-based component registration.
+    """Generic factory class for component registration and creation.

-        class MyFactory(BaseFactory[MyBase]):
+    This base class provides a decorator-based registration pattern
+    for creating extensible component factories.
+
+    Example usage:
+        class MyFactory(BaseFactory[MyBaseClass]):
            pass

        @MyFactory.register("custom")
-        class CustomComponent(MyBase):
+        class CustomComponent(MyBaseClass):
            ...

-        obj = MyFactory.create("custom", *args, **kwargs)
-
-    ``create()`` filters kwargs to match the component's ``__init__``
-    signature so components don't need ``**kwargs`` just to absorb
-    unrelated parameters.
+        component = MyFactory.create("custom", *args, **kwargs)
    """

-    _entries: Dict[str, Type[T]]
+    _registry: Registry

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
-        for orig_base in getattr(cls, "__orig_bases__", ()):
-            if _get_origin(orig_base) is BaseFactory:
-                (arg,) = _get_args(orig_base)
-                cls._entries = {}
-                cls._component_base = _resolve_type(arg, cls)
-                return
+        cls._registry = Registry()

    @classmethod
-    def register(cls, name: str) -> Callable[[Type[T]], Type[T]]:
-        """Decorator to register a component class.
+    def register(
+        cls, name: str, category: Optional[str] = None, priority: int = 0
+    ) -> Callable[[Type[T]], Type[T]]:
+        """Decorator to register a component class with optional category and priority.

-        Validates that the decorated class inherits from the generic
-        type parameter ``T`` declared on the factory.
+        Args:
+            name: Registration name for the component
+            category: Optional category for grouping components
+            priority: Priority for ordering (default 0)
+
+        Returns:
+            Decorator function that registers the component class
+
+        Raises:
+            TypeError: If the decorated class doesn't inherit from the base type
        """

        def decorator(component_cls: Type[T]) -> Type[T]:
            cls._validate_component(component_cls)
-            if name in cls._entries:
-                raise ValueError(f"Component '{name}' is already registered")
-            cls._entries[name] = component_cls
+            cls._registry.register(
+                name, component_cls, category=category, priority=priority
+            )
            return component_cls

        return decorator

    @classmethod
    def create(cls, name: str, *args, **kwargs) -> T:
-        """Create a component instance by name, filtering kwargs to match
-        the component's ``__init__`` signature.
+        """Create a component instance by name.
+
+        Filters kwargs to match the component's __init__ signature,
+        so components don't need to declare **kwargs just to absorb
+        parameters meant for other components.
+
+        Args:
+            name: Registered name of the component
+            *args: Positional arguments passed to component constructor
+            **kwargs: Keyword arguments passed to component constructor
+
+        Returns:
+            Component instance
+
+        Raises:
+            ValueError: If the component name is not registered
        """
-        entry = cls._entries.get(name)
-        if entry is None:
+        if not cls._registry.contains(name):
            raise ValueError(
-                f"Unknown component: '{name}'. Supported types: {sorted(cls._entries)}"
+                f"Unknown component: '{name}'. "
+                f"Supported types: {sorted(cls._registry.list_names())}"
            )
-        component_cls = entry
+        component_cls = cls._registry.get(name)
        sig = inspect.signature(component_cls.__init__)
        has_var_kwargs = any(
            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
@@ -112,33 +158,69 @@ class BaseFactory(ABC, Generic[T]):
        return component_cls(*args, **kwargs)

    @classmethod
-    def _validate_component(cls, component_cls: Type[T]):
-        """Validate the decorated class inherits from the factory's base type.
+    def _validate_component(cls, component_cls: Type[T]) -> None:
+        """Validate that the component class is valid for this factory.

-        Override for custom validation beyond ``issubclass``.
+        Override this method in subclasses to add custom validation.
+
+        Args:
+            component_cls: Component class to validate
+
+        Raises:
+            TypeError: If the component class is invalid
        """
-        base = cls._component_base
-        if base is not None and not issubclass(component_cls, base):
-            raise TypeError(
-                f"{component_cls.__name__} must inherit from {base.__name__}"
-            )
+        pass

    @classmethod
    def get_component_class(cls, name: str) -> Type[T]:
-        """Get the registered component class without instantiating it."""
-        entry = cls._entries.get(name)
-        if entry is None:
+        """Get the registered component class by name without instantiating it.
+
+        Args:
+            name: Registered name of the component
+
+        Returns:
+            The component class itself
+
+        Raises:
+            ValueError: If the component name is not registered
+        """
+        if not cls._registry.contains(name):
            raise ValueError(
-                f"Unknown component: '{name}'. Supported types: {sorted(cls._entries)}"
+                f"Unknown component: '{name}'. "
+                f"Supported types: {sorted(cls._registry.list_names())}"
            )
-        return entry
+        return cls._registry.get(name)

    @classmethod
-    def list_registered(cls) -> List[str]:
-        """List all registered component names."""
-        return sorted(cls._entries)
+    def list_registered(cls) -> list:
+        """List all registered component names.
+
+        Returns:
+            List of registered component names
+        """
+        return cls._registry.list_names()

    @classmethod
    def is_registered(cls, name: str) -> bool:
-        """Check if a component name is registered."""
-        return name in cls._entries
+        """Check if a component name is registered.
+
+        Args:
+            name: Component name to check
+
+        Returns:
+            True if registered, False otherwise
+        """
+        return cls._registry.contains(name)
+
+    @classmethod
+    def list_by_category(cls, category: str) -> List[str]:
+        """List registered component names in a category."""
+        return cls._registry.list_by_category(category)
+
+    @classmethod
+    def list_by_priority(cls, reverse: bool = False) -> List[str]:
+        """List registered component names sorted by priority."""
+        return cls._registry.list_by_priority(reverse)
+
+
+__all__ = ["Registry", "BaseFactory"]
@@ -1,43 +1,32 @@
 """Inference module for continuous batching.

 Layers:
-  - core/:        Core inference loop (cache, executor, scheduler, task)
-  - api/:         HTTP orchestration (ProtocolHandler, server)
-  - protocols/:   Response builders (OpenAI, Anthropic)
-  - transport/:   SSE transport utilities
-  - engine.py:    Facade (InferenceEngine), Value Object (GenerationRequest)
-  - sample.py:    Strategy pattern (TemperatureStrategy, TopKStrategy, TopPStrategy)
+  - core/:           Core inference loop (cache, executor, scheduler, task)
+  - api/:            HTTP protocol handlers (OpenAI, Anthropic)
+  - engine.py:       Facade (InferenceEngine), Value Object (GenerationRequest)
+  - sample.py:       Strategy pattern (TemperatureStrategy, TopKStrategy, TopPStrategy)
 """

 from astrai.inference.api import (
+    AnthropicHandler,
    AnthropicMessage,
-    BaseToolParser,
    ChatCompletionRequest,
    ChatMessage,
-    FunctionDef,
-    GenContext,
    MessagesRequest,
+    OpenAIHandler,
    ProtocolHandler,
-    SimpleJsonToolParser,
    StopChecker,
-    ToolDef,
-    ToolParserFactory,
-    get_app,
+    StreamContext,
+    app,
    run_server,
 )
-from astrai.inference.api.anthropic import AnthropicResponseBuilder
-from astrai.inference.api.openai import OpenAIResponseBuilder
 from astrai.inference.core import (
    STOP,
    Allocator,
-    CacheView,
-    ContiguousCache,
-    ContiguousCacheView,
    Executor,
    InferenceScheduler,
    KVCache,
-    PageCache,
-    PageCacheView,
+    KvcacheView,
    PagePool,
    PrefixCache,
    Storage,
@@ -47,7 +36,10 @@ from astrai.inference.core import (
    TaskTable,
    page_hash,
 )
-from astrai.inference.engine import GenerationRequest, InferenceEngine
+from astrai.inference.engine import (
+    GenerationRequest,
+    InferenceEngine,
+)
 from astrai.inference.sample import (
    BaseSamplingStrategy,
    SamplingPipeline,
@@ -58,46 +50,43 @@ from astrai.inference.sample import (
 )

 __all__ = [
+    # Engine / Requests
    "InferenceEngine",
    "GenerationRequest",
+    # Core scheduler
    "InferenceScheduler",
    "Executor",
    "STOP",
    "Task",
    "TaskManager",
    "TaskStatus",
+    # Core cache
    "Allocator",
-    "CacheView",
    "KVCache",
-    "ContiguousCache",
-    "ContiguousCacheView",
-    "PageCache",
-    "PageCacheView",
+    "KvcacheView",
    "PagePool",
    "PrefixCache",
    "Storage",
    "TaskTable",
    "page_hash",
+    # Sampling (Strategy pattern)
    "sample",
    "BaseSamplingStrategy",
    "TemperatureStrategy",
    "TopKStrategy",
    "TopPStrategy",
    "SamplingPipeline",
+    # Protocol
    "ProtocolHandler",
    "StopChecker",
-    "GenContext",
-    "BaseToolParser",
-    "SimpleJsonToolParser",
-    "ToolParserFactory",
-    "OpenAIResponseBuilder",
-    "AnthropicResponseBuilder",
+    "StreamContext",
+    "AnthropicHandler",
+    "OpenAIHandler",
+    # Server
    "ChatMessage",
    "ChatCompletionRequest",
-    "FunctionDef",
-    "ToolDef",
    "AnthropicMessage",
    "MessagesRequest",
-    "get_app",
+    "app",
    "run_server",
 ]
@@ -1,39 +1,31 @@
-"""Inference API: protocol handler, stop checker, tool parsers, and FastAPI server.
+"""Inference API: protocol handlers and FastAPI server."""

-``app`` is no longer a module-level global. Use :func:`get_app` to access the
-lazy singleton FastAPI instance.
-"""
-
-from astrai.inference.api.protocol import GenContext, ProtocolHandler, StopChecker
+from astrai.inference.api.protocol import (
+    AnthropicHandler,
+    OpenAIHandler,
+    ProtocolHandler,
+    StopChecker,
+    StreamContext,
+)
 from astrai.inference.api.server import (
    AnthropicMessage,
    ChatCompletionRequest,
    ChatMessage,
-    FunctionDef,
    MessagesRequest,
-    ToolDef,
-    get_app,
+    app,
    run_server,
 )
-from astrai.inference.api.tool_parser import (
-    BaseToolParser,
-    SimpleJsonToolParser,
-    ToolParserFactory,
-)

 __all__ = [
+    "AnthropicHandler",
+    "OpenAIHandler",
    "ProtocolHandler",
    "StopChecker",
-    "GenContext",
-    "BaseToolParser",
-    "SimpleJsonToolParser",
-    "ToolParserFactory",
+    "StreamContext",
    "AnthropicMessage",
    "ChatCompletionRequest",
    "ChatMessage",
-    "FunctionDef",
-    "ToolDef",
    "MessagesRequest",
-    "get_app",
+    "app",
    "run_server",
 ]
@@ -1,142 +0,0 @@
-"""Anthropic message completion response builder."""
-
-import time
-import uuid
-from typing import Any, Dict, List, Tuple, Union
-
-from pydantic import BaseModel
-
-from astrai.inference.api.protocol import (
-    GenContext,
-    ResponseBuilder,
-    StopInfo,
-    sse_event,
-)
-from astrai.inference.engine import InferenceEngine
-
-
-def _extract_text(content: Union[str, List[Dict[str, Any]]]) -> str:
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        for block in content:
-            if isinstance(block, dict) and block.get("type") == "text":
-                return block.get("text", "")
-    return ""
-
-
-class AnthropicResponseBuilder(ResponseBuilder):
-    def prepare(
-        self, request: BaseModel, engine: InferenceEngine
-    ) -> Tuple[str, GenContext, List[str]]:
-        messages: List[Dict[str, str]] = []
-        system = getattr(request, "system", None)
-        if system:
-            messages.append({"role": "system", "content": system})
-        for m in request.messages:
-            text = _extract_text(m.content)
-            if text:
-                messages.append({"role": m.role, "content": text})
-        prompt = engine.tokenizer.apply_chat_template(messages, tokenize=False)
-        ctx = GenContext(
-            resp_id=f"msg_{uuid.uuid4().hex[:24]}",
-            created=int(time.time()),
-            model=request.model,
-        )
-        stop_sequences = getattr(request, "stop_sequences", None) or []
-        return prompt, ctx, stop_sequences
-
-    def format_stream_start(self, ctx: GenContext) -> List[str]:
-        return [
-            sse_event(
-                {
-                    "type": "message_start",
-                    "message": {
-                        "id": ctx.resp_id,
-                        "type": "message",
-                        "role": "assistant",
-                        "model": ctx.model,
-                        "content": [],
-                        "usage": {"input_tokens": ctx.prompt_tokens},
-                    },
-                },
-                event="message_start",
-            ),
-            sse_event(
-                {
-                    "type": "content_block_start",
-                    "index": 0,
-                    "content_block": {"type": "text", "text": ""},
-                },
-                event="content_block_start",
-            ),
-        ]
-
-    def format_chunk(self, token: str, **kwargs) -> List[str]:
-        return [
-            sse_event(
-                {
-                    "type": "content_block_delta",
-                    "index": 0,
-                    "delta": {"type": "text_delta", "text": token},
-                },
-                event="content_block_delta",
-            )
-        ]
-
-    def format_stream_end(self, ctx: GenContext, stop: StopInfo) -> List[str]:
-        events: List[str] = []
-        if stop.matched:
-            trimmed = stop.body[: stop.body.rfind(stop.matched)]
-            unyielded = trimmed[len(stop.yielded) :]
-            if unyielded:
-                events.append(
-                    sse_event(
-                        {
-                            "type": "content_block_delta",
-                            "index": 0,
-                            "delta": {"type": "text_delta", "text": unyielded},
-                        },
-                        event="content_block_delta",
-                    )
-                )
-        events.append(
-            sse_event(
-                {"type": "content_block_stop", "index": 0},
-                event="content_block_stop",
-            )
-        )
-        events.append(
-            sse_event(
-                {
-                    "type": "message_delta",
-                    "delta": {
-                        "stop_reason": "stop_sequence" if stop.matched else "end_turn",
-                        "stop_sequence": stop.matched,
-                    },
-                    "usage": {"output_tokens": ctx.completion_tokens},
-                },
-                event="message_delta",
-            )
-        )
-        events.append(sse_event({"type": "message_stop"}, event="message_stop"))
-        return events
-
-    def format_response(
-        self, ctx: GenContext, content: str, stop: StopInfo
-    ) -> Dict[str, Any]:
-        if stop.matched:
-            content = content[: content.rfind(stop.matched)]
-        return {
-            "id": ctx.resp_id,
-            "type": "message",
-            "role": "assistant",
-            "model": ctx.model,
-            "content": [{"type": "text", "text": content}],
-            "stop_reason": "stop_sequence" if stop.matched else "end_turn",
-            "stop_sequence": stop.matched,
-            "usage": {
-                "input_tokens": ctx.prompt_tokens,
-                "output_tokens": ctx.completion_tokens,
-            },
-        }
@@ -1,278 +0,0 @@
-"""OpenAI chat completion response builder."""
-
-import logging
-import time
-import uuid
-from typing import Any, Dict, List, Optional, Tuple, Union
-
-from pydantic import BaseModel
-
-from astrai.inference.api.protocol import (
-    GenContext,
-    ResponseBuilder,
-    StopInfo,
-    sse_event,
-)
-from astrai.inference.api.tool_parser import BaseToolParser, ToolParserFactory
-from astrai.inference.engine import InferenceEngine
-
-logger = logging.getLogger(__name__)
-
-_UNSUPPORTED_PARAMS = (
-    "n",
-    "presence_penalty",
-    "frequency_penalty",
-    "logit_bias",
-    "user",
-)
-
-
-def _resolve_tool_choice(
-    request: BaseModel,
-) -> Union[str, Dict[str, Any]]:
-    tc = getattr(request, "tool_choice", None)
-    if tc is None:
-        return "auto"
-    if isinstance(tc, str):
-        return tc
-    if isinstance(tc, dict):
-        return tc
-    return "auto"
-
-
-def _resolve_tools(request: BaseModel) -> Optional[List[Dict[str, Any]]]:
-    raw = getattr(request, "tools", None)
-    if not raw:
-        return None
-    if isinstance(raw, list):
-        return [t.model_dump() if hasattr(t, "model_dump") else t for t in raw]
-    return None
-
-
-class OpenAIResponseBuilder(ResponseBuilder):
-    def prepare(
-        self, request: BaseModel, engine: InferenceEngine
-    ) -> Tuple[str, GenContext, List[str]]:
-        messages = [{"role": m.role, "content": m.content} for m in request.messages]
-        tools = _resolve_tools(request)
-        prompt = engine.tokenizer.apply_chat_template(
-            messages, tokenize=False, tools=tools or []
-        )
-
-        self._resp_id = f"chatcmpl-{uuid.uuid4().hex[:12]}"
-        self._model = request.model
-
-        for param in _UNSUPPORTED_PARAMS:
-            value = getattr(request, param, None)
-            fields = getattr(type(request), "model_fields", {})
-            default = fields[param].default if param in fields else None
-            if value is not None and value != default:
-                logger.warning(
-                    "ChatCompletionRequest param '%s'=%r is not supported"
-                    " and will be ignored",
-                    param,
-                    value,
-                )
-
-        self._parser: Optional[BaseToolParser] = None
-        if tools:
-            tool_choice = _resolve_tool_choice(request)
-            self._parser = ToolParserFactory.create(
-                "simple_json", tools=tools, tool_choice=tool_choice
-            )
-        self._content_started = False
-
-        ctx = GenContext(
-            resp_id=self._resp_id,
-            created=int(time.time()),
-            model=self._model,
-        )
-        stop = request.stop
-        stop_sequences = (
-            [] if stop is None else [stop] if isinstance(stop, str) else stop
-        )
-        return prompt, ctx, stop_sequences
-
-    def format_stream_start(self, ctx: GenContext) -> List[str]:
-        return [
-            sse_event(
-                {
-                    "id": self._resp_id,
-                    "object": "chat.completion.chunk",
-                    "created": ctx.created,
-                    "model": self._model,
-                    "choices": [
-                        {
-                            "index": 0,
-                            "delta": {"role": "assistant"},
-                            "finish_reason": None,
-                        }
-                    ],
-                }
-            )
-        ]
-
-    def format_chunk(self, token: str, **kwargs) -> List[str]:
-        body = kwargs.get("body", "")
-        if self._parser is not None:
-            return self._format_tool_chunk(body, **kwargs)
-
-        return [
-            sse_event(
-                {
-                    "id": self._resp_id,
-                    "object": "chat.completion.chunk",
-                    "created": 0,
-                    "model": self._model,
-                    "choices": [
-                        {
-                            "index": 0,
-                            "delta": {"content": token},
-                            "finish_reason": None,
-                        }
-                    ],
-                }
-            )
-        ]
-
-    def _format_tool_chunk(self, body: str, **kwargs) -> List[str]:
-        deltas = self._parser.feed(
-            body,
-            current_token_ids=kwargs.get("current_token_ids"),
-            delta_token_ids=kwargs.get("delta_token_ids"),
-        )
-        events: List[str] = []
-        for d in deltas:
-            if "content" in d:
-                if not self._content_started:
-                    events.append(self._role_chunk())
-                    self._content_started = True
-                events.append(
-                    sse_event(
-                        {
-                            "id": self._resp_id,
-                            "object": "chat.completion.chunk",
-                            "created": 0,
-                            "model": self._model,
-                            "choices": [
-                                {
-                                    "index": 0,
-                                    "delta": {"content": d["content"]},
-                                    "finish_reason": None,
-                                }
-                            ],
-                        }
-                    )
-                )
-            elif "tool_calls" in d:
-                if not self._content_started:
-                    events.append(self._role_chunk())
-                    self._content_started = True
-                events.append(
-                    sse_event(
-                        {
-                            "id": self._resp_id,
-                            "object": "chat.completion.chunk",
-                            "created": 0,
-                            "model": self._model,
-                            "choices": [
-                                {
-                                    "index": 0,
-                                    "delta": {"tool_calls": d["tool_calls"]},
-                                    "finish_reason": None,
-                                }
-                            ],
-                        }
-                    )
-                )
-        return events
-
-    def _role_chunk(self) -> str:
-        return sse_event(
-            {
-                "id": self._resp_id,
-                "object": "chat.completion.chunk",
-                "created": 0,
-                "model": self._model,
-                "choices": [
-                    {
-                        "index": 0,
-                        "delta": {"role": "assistant"},
-                        "finish_reason": None,
-                    }
-                ],
-            }
-        )
-
-    def format_stream_end(self, ctx: GenContext, stop: StopInfo) -> List[str]:
-        finish_reason = "stop"
-        if self._parser is not None and self._parser.has_tool_calls:
-            finish_reason = "tool_calls"
-        return [
-            sse_event(
-                {
-                    "id": self._resp_id,
-                    "object": "chat.completion.chunk",
-                    "created": ctx.created,
-                    "model": self._model,
-                    "choices": [
-                        {"index": 0, "delta": {}, "finish_reason": finish_reason}
-                    ],
-                }
-            ),
-            sse_event(
-                {
-                    "prompt_tokens": ctx.prompt_tokens,
-                    "completion_tokens": ctx.completion_tokens,
-                    "total_tokens": ctx.prompt_tokens + ctx.completion_tokens,
-                }
-            ),
-        ]
-
-    def format_response(
-        self, ctx: GenContext, content: str, stop: StopInfo
-    ) -> Dict[str, Any]:
-        if self._parser is not None:
-            parsed = self._parser.parse_complete(content)
-            if parsed and parsed.get("tool_calls"):
-                return {
-                    "id": self._resp_id,
-                    "object": "chat.completion",
-                    "created": ctx.created,
-                    "model": self._model,
-                    "choices": [
-                        {
-                            "index": 0,
-                            "message": {
-                                "role": "assistant",
-                                "content": parsed.get("content"),
-                                "tool_calls": parsed["tool_calls"],
-                            },
-                            "finish_reason": "tool_calls",
-                        }
-                    ],
-                    "usage": {
-                        "prompt_tokens": ctx.prompt_tokens,
-                        "completion_tokens": ctx.completion_tokens,
-                        "total_tokens": ctx.prompt_tokens + ctx.completion_tokens,
-                    },
-                }
-
-        return {
-            "id": self._resp_id,
-            "object": "chat.completion",
-            "created": ctx.created,
-            "model": self._model,
-            "choices": [
-                {
-                    "index": 0,
-                    "message": {"role": "assistant", "content": content},
-                    "finish_reason": "stop",
-                }
-            ],
-            "usage": {
-                "prompt_tokens": ctx.prompt_tokens,
-                "completion_tokens": ctx.completion_tokens,
-                "total_tokens": ctx.prompt_tokens + ctx.completion_tokens,
-            },
-        }
@@ -1,13 +1,15 @@
-"""Orchestration layer: ProtocolHandler, StopChecker, GenContext, StopInfo, ResponseBuilder, SSE utils.
+"""Protocol handlers for OpenAI and Anthropic chat completion APIs.

-ProtocolHandler orchestrates the async generation loop and delegates
-protocol-specific formatting to a ResponseBuilder.
+Template Method + Builder patterns eliminate the 45% code duplication between
+stream/non-stream branches and across protocol adapters.
 """

 import json
+import time
+import uuid
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Any, AsyncGenerator, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Union

 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
@@ -15,7 +17,7 @@ from pydantic import BaseModel
 from astrai.inference.engine import InferenceEngine


-def sse_event(data: Dict[str, Any], event: Optional[str] = None) -> str:
+def _sse_event(data: Dict[str, Any], event: Optional[str] = None) -> str:
    lines: List[str] = []
    if event:
        lines.append(f"event: {event}")
@@ -24,28 +26,22 @@ def sse_event(data: Dict[str, Any], event: Optional[str] = None) -> str:
    return "\n".join(lines)


-def sse_done() -> str:
+def _sse_done() -> str:
    return "data: [DONE]\n\n"


@dataclass
-class GenContext:
-    """Per-generation metadata passed to builder format methods."""
+class StreamContext:
+    """Shared state across the streaming generation lifecycle."""

    resp_id: str
    created: int
    model: str
-    prompt_tokens: int = 0
+    prompt_tokens: int
    completion_tokens: int = 0
-
-
-@dataclass
-class StopInfo:
-    """Stop-check result passed to format_stream_end / format_response."""
-
-    matched: Optional[str] = None
-    body: str = ""
-    yielded: str = ""
+    accumulated: str = ""
+    stop_matched: Optional[str] = None
+    last_yield_trimmed: str = ""


 class StopChecker:
@@ -60,67 +56,95 @@ class StopChecker:
                return seq
        return None

+    def trim(self, text: str, matched: str) -> str:
+        idx = text.rfind(matched)
+        return text[:idx] if idx != -1 else text

-class ResponseBuilder(ABC):
-    """Interface for protocol-specific response formatting.
+    @property
+    def has_sequences(self) -> bool:
+        return len(self._sequences) > 0

-    A new protocol requires one concrete builder implementing 5 methods.
+
+class ProtocolHandler(ABC):
+    """Template-method base for API protocol handlers.
+
+    Subclasses implement format hooks; the base class orchestrates the
+    generate-async loop and SSE/JSON response construction.
+
+    Lifecycle::
+
+        handle()
+          ├─ build_prompt()          # protocol-specific prompt assembly
+          ├─ create_response_id()    # unique response identifier
+          ├─ [stream]
+          │   ├─ format_stream_start()
+          │   ├─ format_stream_token()  × N
+          │   │   └─ on_token() hook for stop-sequence interception
+          │   └─ format_stream_end()
+          └─ [non-stream]
+              ├─ (accumulate tokens)
+              └─ format_non_stream_response()
    """

-    @abstractmethod
-    def prepare(
-        self, request: BaseModel, engine: InferenceEngine
-    ) -> Tuple[str, GenContext, List[str]]:
-        """Return (prompt, ctx, stop_sequences) for a generation request."""
+    request_model: type[BaseModel]

-    @abstractmethod
-    def format_stream_start(self, ctx: GenContext) -> List[str]:
-        """SSE events that open the stream."""
-
-    @abstractmethod
-    def format_chunk(self, token: str, **kwargs) -> List[str]:
-        """SSE events for a single generated token.
-
-        ``body`` (the full accumulated text so far) is always provided
-        as a keyword argument. Additional keyword arguments such as
-        ``current_token_ids`` and ``delta_token_ids`` may be included
-        for tool parsers that need token-level information.
-        Returns a list of SSE event strings (may be empty).
-        """
-
-    @abstractmethod
-    def format_stream_end(self, ctx: GenContext, stop: StopInfo) -> List[str]:
-        """SSE events that close the stream."""
-
-    @abstractmethod
-    def format_response(
-        self, ctx: GenContext, content: str, stop: StopInfo
-    ) -> Dict[str, Any]:
-        """JSON response body for non-streaming mode."""
-
-
-class ProtocolHandler:
-    """Orchestrates the generation loop, delegates formatting to a builder.
-
-    Usage::
-
-        handler = ProtocolHandler(request, engine, OpenAIResponseBuilder())
-        response = await handler.handle()
-    """
-
-    def __init__(
-        self, request: BaseModel, engine: InferenceEngine, builder: ResponseBuilder
-    ):
+    def __init__(self, request: BaseModel, engine: InferenceEngine):
        self.request = request
        self.engine = engine
-        self.builder = builder
+
+    @abstractmethod
+    def build_prompt(self) -> str:
+        """Build the full prompt string from the request messages."""
+
+    @abstractmethod
+    def create_response_id(self) -> str:
+        """Generate a unique response ID following the protocol convention."""
+
+    @abstractmethod
+    def format_stream_start(self, ctx: StreamContext) -> List[str]:
+        """Yield SSE events that open the stream (role marker, metadata)."""
+
+    @abstractmethod
+    def format_stream_token(self, ctx: StreamContext, token: str) -> str:
+        """Yield an SSE event for a single generated token."""
+
+    @abstractmethod
+    def format_stream_end(self, ctx: StreamContext) -> List[str]:
+        """Yield SSE events that close the stream (finish reason, usage stats)."""
+
+    @abstractmethod
+    def format_non_stream_response(
+        self, ctx: StreamContext, content: str
+    ) -> Dict[str, Any]:
+        """Build the JSON response body for non-streaming mode."""
+
+    def get_stop_sequences(self) -> List[str]:
+        return []
+
+    def create_stop_checker(self) -> StopChecker:
+        return StopChecker(self.get_stop_sequences())
+
+    def on_token(
+        self, ctx: StreamContext, token: str, stop_checker: StopChecker
+    ) -> Optional[str]:
+        """Hook after each token is appended to accumulated.
+
+        Return a matched stop-sequence string to break the loop,
+        or None to continue.
+
+        """
+        return None

    async def handle(self) -> Union[StreamingResponse, Dict[str, Any]]:
-        prompt, ctx, stop_sequences = self.builder.prepare(self.request, self.engine)
-        ctx.prompt_tokens = len(self.engine.tokenizer.encode(prompt))
+        ctx = StreamContext(
+            resp_id=self.create_response_id(),
+            created=int(time.time()),
+            model=self.request.model,
+            prompt_tokens=self._count_prompt_tokens(),
+        )

        agen = self.engine.generate_async(
-            prompt=prompt,
+            prompt=self.build_prompt(),
            max_tokens=self.request.max_tokens,
            temperature=self.request.temperature,
            top_p=self.request.top_p,
@@ -128,47 +152,33 @@ class ProtocolHandler:
        )

        if self.request.stream:
-            return self._handle_stream(agen, ctx, stop_sequences)
+            return self._handle_stream(agen, ctx)
        else:
-            return await self._handle_non_stream(agen, ctx, stop_sequences)
+            return await self._handle_non_stream(agen, ctx)

-    def _handle_stream(
-        self, agen: AsyncGenerator, ctx: GenContext, stop_sequences: List[str]
-    ) -> StreamingResponse:
-        checker = StopChecker(stop_sequences)
+    def _count_prompt_tokens(self) -> int:
+        return len(self.engine.tokenizer.encode(self.build_prompt()))
+
+    def _handle_stream(self, agen, ctx: StreamContext) -> StreamingResponse:
+        stop_checker = self.create_stop_checker()

        async def event_stream():
-            for event in self.builder.format_stream_start(ctx):
+            for event in self.format_stream_start(ctx):
                yield event

-            body = ""
-            yielded = ""
-            matched = None
-            token_ids: List[int] = []
            async for token in agen:
-                body += token
+                ctx.completion_tokens += 1
+                ctx.accumulated += token

-                new_ids = self.engine.tokenizer.encode(token)
-                token_ids.extend(new_ids)
-
-                matched = checker.check(body)
+                matched = self.on_token(ctx, token, stop_checker)
                if matched:
                    break

-                ctx.completion_tokens += 1
-                for event in self.builder.format_chunk(
-                    token,
-                    body=body,
-                    current_token_ids=token_ids,
-                    delta_token_ids=new_ids,
-                ):
-                    yield event
-                yielded += token
+                yield self.format_stream_token(ctx, token)

-            stop = StopInfo(matched=matched, body=body, yielded=yielded)
-            for event in self.builder.format_stream_end(ctx, stop):
+            for event in self.format_stream_end(ctx):
                yield event
-            yield sse_done()
+            yield _sse_done()

        return StreamingResponse(
            event_stream(),
@@ -176,24 +186,249 @@ class ProtocolHandler:
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

-    async def _handle_non_stream(
-        self, agen: AsyncGenerator, ctx: GenContext, stop_sequences: List[str]
-    ) -> Dict[str, Any]:
-        checker = StopChecker(stop_sequences)
+    async def _handle_non_stream(self, agen, ctx: StreamContext) -> Dict[str, Any]:
+        stop_checker = self.create_stop_checker()
        chunks: List[str] = []
-        body = ""
-        matched = None

        async for token in agen:
+            ctx.completion_tokens += 1
+            ctx.accumulated += token
            chunks.append(token)
-            body += token

-            matched = checker.check(body)
+            matched = self.on_token(ctx, token, stop_checker)
            if matched:
                break

-            ctx.completion_tokens += 1
-
        content = "".join(chunks)
-        stop = StopInfo(matched=matched, body=body)
-        return self.builder.format_response(ctx, content, stop)
+        return self.format_non_stream_response(ctx, content)
+
+
+def _extract_text_content(content: Union[str, List[Dict[str, Any]]]) -> str:
+    """Extract plain text from an Anthropic content block (string or list)."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                return block.get("text", "")
+    return ""
+
+
+class OpenAIHandler(ProtocolHandler):
+    """OpenAI-compatible /v1/chat/completions handler."""
+
+    def build_prompt(self) -> str:
+        messages = [
+            {"role": m.role, "content": m.content} for m in self.request.messages
+        ]
+        return self.engine.tokenizer.apply_chat_template(messages, tokenize=False)
+
+    def create_response_id(self) -> str:
+        return f"chatcmpl-{uuid.uuid4().hex[:12]}"
+
+    def format_stream_start(self, ctx: StreamContext) -> List[str]:
+        return [
+            _sse_event(
+                {
+                    "id": ctx.resp_id,
+                    "object": "chat.completion.chunk",
+                    "created": ctx.created,
+                    "model": ctx.model,
+                    "choices": [
+                        {
+                            "index": 0,
+                            "delta": {"role": "assistant"},
+                            "finish_reason": None,
+                        }
+                    ],
+                }
+            )
+        ]
+
+    def format_stream_token(self, ctx: StreamContext, token: str) -> str:
+        return _sse_event(
+            {
+                "id": ctx.resp_id,
+                "object": "chat.completion.chunk",
+                "created": ctx.created,
+                "model": ctx.model,
+                "choices": [
+                    {"index": 0, "delta": {"content": token}, "finish_reason": None}
+                ],
+            }
+        )
+
+    def format_stream_end(self, ctx: StreamContext) -> List[str]:
+        return [
+            _sse_event(
+                {
+                    "id": ctx.resp_id,
+                    "object": "chat.completion.chunk",
+                    "created": ctx.created,
+                    "model": ctx.model,
+                    "choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}],
+                }
+            ),
+            _sse_event(
+                {
+                    "prompt_tokens": ctx.prompt_tokens,
+                    "completion_tokens": ctx.completion_tokens,
+                    "total_tokens": ctx.prompt_tokens + ctx.completion_tokens,
+                }
+            ),
+        ]
+
+    def format_non_stream_response(
+        self, ctx: StreamContext, content: str
+    ) -> Dict[str, Any]:
+        return {
+            "id": ctx.resp_id,
+            "object": "chat.completion",
+            "created": ctx.created,
+            "model": ctx.model,
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {"role": "assistant", "content": content},
+                    "finish_reason": "stop",
+                }
+            ],
+            "usage": {
+                "prompt_tokens": ctx.prompt_tokens,
+                "completion_tokens": ctx.completion_tokens,
+                "total_tokens": ctx.prompt_tokens + ctx.completion_tokens,
+            },
+        }
+
+
+class AnthropicHandler(ProtocolHandler):
+    """Anthropic-compatible /v1/messages handler."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._yielded = ""
+
+    def build_prompt(self) -> str:
+        messages: List[Dict[str, str]] = []
+        system = getattr(self.request, "system", None)
+        if system:
+            messages.append({"role": "system", "content": system})
+        for m in self.request.messages:
+            content = _extract_text_content(m.content)
+            if content:
+                messages.append({"role": m.role, "content": content})
+        return self.engine.tokenizer.apply_chat_template(messages, tokenize=False)
+
+    def create_response_id(self) -> str:
+        return f"msg_{uuid.uuid4().hex[:24]}"
+
+    def get_stop_sequences(self) -> List[str]:
+        return getattr(self.request, "stop_sequences", None) or []
+
+    def on_token(
+        self, ctx: StreamContext, token: str, stop_checker: StopChecker
+    ) -> Optional[str]:
+        matched = stop_checker.check(ctx.accumulated)
+        if not matched:
+            return None
+
+        ctx.stop_matched = matched
+        trimmed = ctx.accumulated[: ctx.accumulated.rfind(matched)]
+        unyielded = trimmed[len(self._yielded) :]
+        if unyielded:
+            ctx.last_yield_trimmed = unyielded
+        return matched
+
+    def format_stream_start(self, ctx: StreamContext) -> List[str]:
+        return [
+            _sse_event(
+                {
+                    "type": "message_start",
+                    "message": {
+                        "id": ctx.resp_id,
+                        "type": "message",
+                        "role": "assistant",
+                        "model": ctx.model,
+                        "content": [],
+                        "usage": {"input_tokens": ctx.prompt_tokens},
+                    },
+                },
+                event="message_start",
+            ),
+            _sse_event(
+                {
+                    "type": "content_block_start",
+                    "index": 0,
+                    "content_block": {"type": "text", "text": ""},
+                },
+                event="content_block_start",
+            ),
+        ]
+
+    def format_stream_token(self, ctx: StreamContext, token: str) -> str:
+        self._yielded += token
+        return _sse_event(
+            {
+                "type": "content_block_delta",
+                "index": 0,
+                "delta": {"type": "text_delta", "text": token},
+            },
+            event="content_block_delta",
+        )
+
+    def format_stream_end(self, ctx: StreamContext) -> List[str]:
+        matched = ctx.stop_matched
+        events: List[str] = []
+        last_yielded = ctx.last_yield_trimmed
+        if last_yielded:
+            events.append(
+                _sse_event(
+                    {
+                        "type": "content_block_delta",
+                        "index": 0,
+                        "delta": {"type": "text_delta", "text": last_yielded},
+                    },
+                    event="content_block_delta",
+                )
+            )
+        events.append(
+            _sse_event(
+                {"type": "content_block_stop", "index": 0},
+                event="content_block_stop",
+            )
+        )
+        events.append(
+            _sse_event(
+                {
+                    "type": "message_delta",
+                    "delta": {
+                        "stop_reason": "stop_sequence" if matched else "end_turn",
+                        "stop_sequence": matched,
+                    },
+                    "usage": {"output_tokens": ctx.completion_tokens},
+                },
+                event="message_delta",
+            )
+        )
+        events.append(_sse_event({"type": "message_stop"}, event="message_stop"))
+        return events
+
+    def format_non_stream_response(
+        self, ctx: StreamContext, content: str
+    ) -> Dict[str, Any]:
+        matched = ctx.stop_matched
+        if matched:
+            content = content[: content.rfind(matched)]
+        return {
+            "id": ctx.resp_id,
+            "type": "message",
+            "role": "assistant",
+            "model": ctx.model,
+            "content": [{"type": "text", "text": content}],
+            "stop_reason": "stop_sequence" if matched else "end_turn",
+            "stop_sequence": matched,
+            "usage": {
+                "input_tokens": ctx.prompt_tokens,
+                "output_tokens": ctx.completion_tokens,
+            },
+        }
@@ -3,9 +3,6 @@ OpenAI / Anthropic-compatible chat completion server backed by continuous-batchi

 Protocol-specific formatting is delegated to ``astrai.inference.protocol``.
 This module owns the FastAPI app, request/response schemas, and dependency wiring.
-
-``app`` is lazily constructed — importing this module does NOT create a FastAPI instance.
-Use :func:`get_app` to access the singleton.
 """

 import logging
@@ -15,37 +12,22 @@ from typing import Any, Dict, List, Optional, Union

 import torch
 import uvicorn
-from fastapi import APIRouter, FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel, Field

-from astrai.inference.api.anthropic import AnthropicResponseBuilder
-from astrai.inference.api.openai import OpenAIResponseBuilder
-from astrai.inference.api.protocol import ProtocolHandler
+from astrai.inference.api.protocol import AnthropicHandler, OpenAIHandler
 from astrai.inference.engine import InferenceEngine
 from astrai.model import AutoModel
 from astrai.tokenize import AutoTokenizer

 logger = logging.getLogger(__name__)

-_app_instance: Optional[FastAPI] = None
+_project_root = Path(__file__).parent.parent.parent


 class ChatMessage(BaseModel):
    role: str
-    content: Optional[str] = None
-    tool_calls: Optional[List[Dict[str, Any]]] = None
-    tool_call_id: Optional[str] = None
-
-
-class FunctionDef(BaseModel):
-    name: str
-    description: Optional[str] = None
-    parameters: Optional[Dict[str, Any]] = None
-
-
-class ToolDef(BaseModel):
-    type: str = "function"
-    function: FunctionDef
+    content: str


 class ChatCompletionRequest(BaseModel):
@@ -64,8 +46,6 @@ class ChatCompletionRequest(BaseModel):
    frequency_penalty: Optional[float] = Field(default=0.0, ge=-2.0, le=2.0)
    logit_bias: Optional[Dict[int, float]] = None
    user: Optional[str] = None
-    tools: Optional[List[ToolDef]] = None
-    tool_choice: Optional[Union[str, Dict[str, Any]]] = "auto"


 class AnthropicMessage(BaseModel):
@@ -102,15 +82,17 @@ async def lifespan(app: FastAPI):
        logger.info("Inference engine shutdown complete")


-router = APIRouter()
+app = FastAPI(title="AstrAI Inference Server", version="0.2.0", lifespan=lifespan)


 def _create_engine(
-    param_path: Path,
+    param_path: Optional[Path] = None,
    device: str = "cuda",
    dtype: torch.dtype = torch.bfloat16,
    max_batch_size: int = 16,
 ) -> InferenceEngine:
+    if param_path is None:
+        param_path = _project_root / "params"
    if not param_path.exists():
        raise FileNotFoundError(f"Parameter directory not found: {param_path}")

@@ -128,66 +110,49 @@ def _create_engine(
    return engine


-def get_app() -> FastAPI:
-    """Return the singleton FastAPI instance (lazily created on first call)."""
-    global _app_instance
-    if _app_instance is None:
-        _app_instance = FastAPI(
-            title="AstrAI Inference Server",
-            version="0.2.0",
-            lifespan=lifespan,
-        )
-        _app_instance.include_router(router)
-        _app_instance.state.server_config = {}
-        _app_instance.state.engine = None
-    return _app_instance
-
-
 def _get_engine() -> InferenceEngine:
-    engine = get_app().state.engine
+    engine = app.state.engine
    if engine is None:
        raise HTTPException(status_code=503, detail="Engine not initialized")
    return engine


-@router.get("/health")
+@app.get("/health")
 async def health():
-    app = get_app()
    return {
        "status": "ok",
        "model_loaded": app.state.engine is not None,
    }


-@router.get("/stats")
+@app.get("/stats")
 async def get_stats():
    return _get_engine().get_stats()


-@router.post("/v1/chat/completions")
+@app.post("/v1/chat/completions")
 async def chat_completion(request: ChatCompletionRequest):
    engine = _get_engine()
-    handler = ProtocolHandler(request, engine, OpenAIResponseBuilder())
+    handler = OpenAIHandler(request, engine)
    return await handler.handle()


-@router.post("/v1/messages")
+@app.post("/v1/messages")
 async def create_message(request: MessagesRequest):
    engine = _get_engine()
-    handler = ProtocolHandler(request, engine, AnthropicResponseBuilder())
+    handler = AnthropicHandler(request, engine)
    return await handler.handle()


 def run_server(
-    param_path: Path,
    host: str = "0.0.0.0",
    port: int = 8000,
    reload: bool = False,
    device: str = "cuda",
    dtype: torch.dtype = torch.bfloat16,
+    param_path: Optional[Path] = None,
    max_batch_size: int = 16,
 ):
-    app = get_app()
    app.state.server_config = {
        "device": device,
        "dtype": dtype,
@@ -1,325 +0,0 @@
-"""Tool call parsers for extracting structured tool calls from model output.
-
-Patterned after vLLM's ToolParser abstraction. Each parser knows how to
-detect and incrementally extract tool calls from raw generated text.
-
-Subclasses may optionally consume ``token_ids`` for token-level parsing
-(e.g. Harmony / VLM-style parsers).
-"""
-
-import re
-import uuid
-from abc import ABC, abstractmethod
-from typing import Dict, List, Optional
-
-from astrai.factory import BaseFactory
-
-
-class BaseToolParser(ABC):
-    """Abstract tool call parser — one instance per request.
-
-    Maintains streaming state internally so that each call to :meth:`feed`
-    can diff against previously emitted content.
-
-    Parameters
-    ----------
-    tools : list of dict, optional
-        Tool definitions from the request.
-    tool_choice : str
-        ``"auto"`` / ``"required"`` / ``"none"`` or a named tool choice
-        dict.
-    """
-
-    def __init__(self, tools: Optional[List[Dict]] = None, tool_choice: str = "auto"):
-        self.tools = tools or []
-        self.tool_choice = tool_choice
-
-    @abstractmethod
-    def feed(
-        self,
-        body: str,
-        current_token_ids: Optional[List[int]] = None,
-        delta_token_ids: Optional[List[int]] = None,
-    ) -> List[Dict]:
-        """Feed the *full* accumulated text each step.
-
-        Returns a list of delta dicts to emit. Each delta is one of:
-
-        - ``{"content": "text"}``      — plain text delta
-        - ``{"tool_calls": [...]}``    — tool-call delta (OpenAI format)
-
-        Returns an empty list when nothing new should be emitted.
-
-        Parameters
-        ----------
-        body : str
-            The complete accumulated generated text so far.
-        current_token_ids : list of int, optional
-            All token IDs decoded into *body* (cumulative).
-        delta_token_ids : list of int, optional
-            Only the token IDs for this chunk.
-        """
-
-    @abstractmethod
-    def parse_complete(self, body: str) -> Optional[Dict]:
-        """Parse the *complete* generated text after generation ends.
-
-        Returns ``None`` when no tool calls were found, otherwise a dict
-        with ``content`` (str or None) and ``tool_calls`` (list of dicts).
-        """
-
-    @property
-    @abstractmethod
-    def has_tool_calls(self) -> bool:
-        """True if the parser detected at least one tool call in the stream."""
-
-
-class ToolParserFactory(BaseFactory["BaseToolParser"]):
-    pass
-
-
-_TOOL_CALL_HEAD_RE = re.compile(r'\{\s*"name"\s*:')
-
-
-def _scan_json(text: str, start: int = 0):
-    """Scan for a complete JSON object starting at *start*.
-
-    Returns ``(end, complete)`` where *end* is one-past the closing
-    brace (or ``len(text)`` if unclosed), and *complete* is a bool.
-    """
-    depth = 0
-    in_string = False
-    escape = False
-    for i in range(start, len(text)):
-        c = text[i]
-        if escape:
-            escape = False
-            continue
-        if c == "\\":
-            escape = True
-            continue
-        if c == '"':
-            in_string = not in_string
-            continue
-        if in_string:
-            continue
-        if c == "{":
-            depth += 1
-        elif c == "}":
-            depth -= 1
-            if depth == 0:
-                return i + 1, True
-    return len(text), False
-
-
-def _parse_tool_call_json(json_str: str, complete: bool):
-    """Extract *name* and *arguments* from a tool-call JSON string.
-
-    Returns ``(name, args, valid)``.
-    """
-    name_match = re.search(r'"name"\s*:\s*"([^"]*)"', json_str)
-    if not name_match:
-        return None, "", False
-    name = name_match.group(1)
-
-    args_match = re.search(r'"arguments"\s*:\s*(.*)', json_str, re.DOTALL)
-    if not args_match:
-        return name, "", True
-
-    raw = args_match.group(1).rstrip()
-    if complete and raw.endswith("}"):
-        raw = raw[:-1].rstrip()
-    if raw.startswith("{"):
-        inner = raw[1:].rstrip()
-        if inner.endswith("}"):
-            inner = inner[:-1].rstrip()
-        raw = inner
-    return name, raw, True
-
-
-def _find_tool_calls(text: str, start_pos: int = 0):
-    """Find all complete ``{...}`` tool-call objects in *text*.
-
-    Returns a list of dicts with keys *start*, *end*, *name*, *args*,
-    *complete*.
-    """
-    results = []
-    pos = start_pos
-
-    while True:
-        brace = text.find("{", pos)
-        if brace == -1:
-            break
-
-        end, complete = _scan_json(text, brace)
-        if not complete:
-            break
-
-        json_str = text[brace:end]
-        if not _TOOL_CALL_HEAD_RE.search(json_str):
-            pos = end
-            continue
-
-        name, args, valid = _parse_tool_call_json(json_str, complete=True)
-        if not valid or name is None:
-            pos = end
-            continue
-
-        results.append(
-            {
-                "start": brace,
-                "end": end,
-                "name": name,
-                "args": args,
-                "complete": True,
-            }
-        )
-        pos = end
-
-    return results
-
-
-def _find_partial_tool_call(text: str, start_pos: int = 0):
-    """Find one incomplete (still-generating) tool-call JSON object."""
-    brace = text.find("{", start_pos)
-    if brace == -1:
-        return None
-
-    json_str = text[brace:]
-    if not _TOOL_CALL_HEAD_RE.search(json_str):
-        return None
-
-    name, args, valid = _parse_tool_call_json(json_str, complete=False)
-    if not valid or name is None:
-        return None
-
-    return {
-        "start": brace,
-        "name": name,
-        "args": args,
-        "complete": False,
-    }
-
-
-@ToolParserFactory.register("simple_json")
-class SimpleJsonToolParser(BaseToolParser):
-    """Parser for models that output tool calls as plain JSON objects.
-
-    Detects ``{"name": "<func>", "arguments": {...}}`` anywhere in the
-    generated text.  Handles single and (non-overlapping) multiple tool
-    calls.  Text preceding the first tool call is emitted as plain
-    ``content`` deltas.
-    """
-
-    def __init__(self, tools=None, tool_choice="auto"):
-        super().__init__(tools, tool_choice)
-        self._emitted_content_len = 0
-        self._tc_state: List[Dict] = []
-        self._has_tool_calls = False
-
-    # -------------------------------------------------------------- feed
-
-    def feed(
-        self,
-        body: str,
-        current_token_ids: Optional[List[int]] = None,
-        delta_token_ids: Optional[List[int]] = None,
-    ) -> List[Dict]:
-        deltas: List[Dict] = []
-
-        completed = _find_tool_calls(body)
-
-        if not completed:
-            partial = _find_partial_tool_call(body)
-            if not partial:
-                return self._emit_plain_content(body, deltas)
-            all_tcs = [partial]
-        else:
-            all_tcs = completed
-            partial = _find_partial_tool_call(body, completed[-1]["end"])
-            if partial:
-                all_tcs = completed + [partial]
-
-        first_start = all_tcs[0]["start"]
-        if first_start > self._emitted_content_len:
-            content = body[self._emitted_content_len : first_start]
-            self._emitted_content_len = first_start
-            if content:
-                deltas.append({"content": content})
-
-        for i, tc in enumerate(all_tcs):
-            if i >= len(self._tc_state):
-                self._tc_state.append(
-                    {
-                        "id": f"call_{uuid.uuid4().hex[:12]}",
-                        "name_emitted": False,
-                        "args_emitted_len": 0,
-                    }
-                )
-                self._has_tool_calls = True
-            st = self._tc_state[i]
-
-            if not st["name_emitted"]:
-                st["name_emitted"] = True
-                deltas.append(
-                    {
-                        "tool_calls": [
-                            {
-                                "index": i,
-                                "id": st["id"],
-                                "type": "function",
-                                "function": {"name": tc["name"], "arguments": ""},
-                            }
-                        ]
-                    }
-                )
-
-            new_args = tc["args"]
-            if len(new_args) > st["args_emitted_len"]:
-                diff = new_args[st["args_emitted_len"] :]
-                st["args_emitted_len"] = len(new_args)
-                deltas.append(
-                    {
-                        "tool_calls": [
-                            {
-                                "index": i,
-                                "function": {"arguments": diff},
-                            }
-                        ]
-                    }
-                )
-
-        return deltas
-
-    def _emit_plain_content(self, body: str, deltas: List[Dict]) -> List[Dict]:
-        new_content = body[self._emitted_content_len :]
-        if new_content:
-            self._emitted_content_len = len(body)
-            deltas.append({"content": new_content})
-        return deltas
-
-    # -------------------------------------------------------- complete
-
-    def parse_complete(self, body: str) -> Optional[Dict]:
-        completed = _find_tool_calls(body)
-        if not completed:
-            return None
-
-        content = body[: completed[0]["start"]].strip() or None
-        tool_calls = []
-        for i, tc in enumerate(completed):
-            tool_calls.append(
-                {
-                    "id": f"call_{uuid.uuid4().hex[:12]}",
-                    "type": "function",
-                    "function": {
-                        "name": tc["name"],
-                        "arguments": tc["args"],
-                    },
-                }
-            )
-        return {"content": content, "tool_calls": tool_calls}
-
-    @property
-    def has_tool_calls(self) -> bool:
-        return self._has_tool_calls
@@ -2,12 +2,8 @@

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

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

@@ -43,7 +42,7 @@ class Allocator:
                return idx
            return -1

-    def free(self, idx: int, keep_cached: bool = False):
+    def free(self, idx: int, keep_cached: bool = False) -> None:
        with self._lock:
            self._refs[idx] -= 1
            if self._refs[idx] == 0:
@@ -52,7 +51,7 @@ class Allocator:
                else:
                    self._free_mask |= 1 << idx

-    def inc_ref(self, idx: int):
+    def inc_ref(self, idx: int) -> None:
        with self._lock:
            self._refs[idx] += 1
            self._lru.pop(idx, None)
@@ -61,10 +60,9 @@ class Allocator:
        with self._lock:
            return self._refs[idx]

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


 class PrefixCache:
@@ -76,7 +74,7 @@ class PrefixCache:
        self._hash_to_page: Dict[int, int] = {}
        self._lock = threading.Lock()

-    def evict(self, idx: int):
+    def evict(self, idx: int) -> None:
        with self._lock:
            h = self._page_to_hash.pop(idx, None)
            if h is not None:
@@ -98,7 +96,9 @@ class PrefixCache:
                hits.append(p)
            return hits

-    def record(self, page_idx: int, token_ids: List[int], logical_page_idx: int):
+    def record(
+        self, page_idx: int, token_ids: List[int], logical_page_idx: int
+    ) -> None:
        with self._lock:
            h = page_hash(token_ids, logical_page_idx, self._page_size)
            old_h = self._page_to_hash.pop(page_idx, None)
@@ -127,13 +127,13 @@ class PagePool:
    def alloc(self) -> int:
        return self._alloc.alloc()

-    def free(self, idx: int):
+    def free(self, idx: int) -> None:
        keep = self._prefix.has_page(idx)
        self._alloc.free(idx, keep_cached=keep)
        if not keep:
            self._prefix.evict(idx)

-    def inc_ref(self, idx: int):
+    def inc_ref(self, idx: int) -> None:
        self._alloc.inc_ref(idx)

    def lookup(self, token_ids: List[int]) -> List[int]:
@@ -142,7 +142,9 @@ class PagePool:
            self._alloc.touch(p)
        return hits

-    def record(self, page_idx: int, token_ids: List[int], logical_page_idx: int):
+    def record(
+        self, page_idx: int, token_ids: List[int], logical_page_idx: int
+    ) -> None:
        self._prefix.record(page_idx, token_ids, logical_page_idx)


@@ -155,7 +157,7 @@ class TaskTable:
        self._cached: Dict[str, int] = {}
        self._lock = threading.Lock()

-    def set(self, task_id: str, page_table: List[int], cached: int):
+    def set(self, task_id: str, page_table: List[int], cached: int) -> None:
        with self._lock:
            self._pages[task_id] = page_table
            self._cached[task_id] = cached
@@ -218,7 +220,7 @@ class Storage:
        start_pos: int,
        k: Tensor,
        v: Tensor,
-    ):
+    ) -> None:
        seq_len = k.size(1)
        if seq_len == 0:
            return
@@ -276,42 +278,7 @@ class Storage:
        return k, v


-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):
+class KvcacheView:
    """Bundles Storage + page_table + total_len for attention layers."""

    def __init__(self, storage: Storage, page_table: Tensor, total_len: int = 0):
@@ -319,7 +286,7 @@ class PageCacheView(CacheView):
        self._page_table = page_table
        self._total_len = total_len

-    def write(self, layer_id: int, k: Tensor, v: Tensor):
+    def write(self, layer_id: int, k: Tensor, v: Tensor) -> None:
        start_pos = self._total_len - k.size(1)
        self._storage.write(layer_id, self._page_table, start_pos, k, v)

@@ -327,8 +294,8 @@ class PageCacheView(CacheView):
        return self._storage.gather(layer_id, self._page_table, self._total_len)


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

    def __init__(
        self,
@@ -372,7 +339,7 @@ class PageCache(KVCache):
        self._table.set(task_id, hits + new_pages, cached)
        return True

-    def task_free(self, task_id: str):
+    def task_free(self, task_id: str) -> None:
        page_table, _ = self._table.pop(task_id)
        for idx in page_table:
            self._pool.free(idx)
@@ -392,108 +359,14 @@ class PageCache(KVCache):

    def task_record_hashes(
        self, task_id: str, prompt_ids: List[int], start_logical_page: int = 0
-    ):
+    ) -> None:
        page_table = self._table.get(task_id)
        full_pages = len(prompt_ids) // self.page_size
        for i in range(start_logical_page, full_pages):
            self._pool.record(page_table[i], prompt_ids, i)

-    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 make_table_tensor(self, task_ids: List[str], device: torch.device) -> Tensor:
+        return self._table.table_tensor(task_ids, device)

-
-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)
+    def bind(self, page_table: Tensor, total_len: int = 0) -> KvcacheView:
+        return KvcacheView(self._storage, page_table, total_len)
@@ -19,17 +19,19 @@ class Executor:
        self,
        model: AutoModel,
        tokenizer: AutoTokenizer,
-        kv_cache: KVCache,
+        page_cache: KVCache,
        device: Optional[str] = None,
        dtype: Optional[torch.dtype] = None,
    ):
        self.model = model
        self.tokenizer = tokenizer
-        self.kv_cache = kv_cache
+        self.page_cache = page_cache
        self.device = device or next(model.parameters()).device
        self.dtype = dtype or next(model.parameters()).dtype

-    def execute_prefill(self, tasks: List[Task], prompt_len: int, start_pos: int = 0):
+    def execute_prefill(
+        self, tasks: List[Task], prompt_len: int, start_pos: int = 0
+    ) -> None:
        if start_pos >= prompt_len:
            return

@@ -43,6 +45,7 @@ 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(
@@ -52,7 +55,7 @@ class Executor:
                )
                .unsqueeze(0)
                .expand(batch_sz, -1),
-                paged_cache=self.kv_cache.bind_tasks(task_ids, prompt_len, self.device),
+                paged_cache=self.page_cache.bind(page_tables, total_len=prompt_len),
            )

    def execute_decode(self, tasks: List[Task]) -> List[int]:
@@ -71,6 +74,7 @@ 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)
@@ -79,7 +83,7 @@ class Executor:
        with torch.inference_mode():
            outputs = self.model(
                input_ids.unsqueeze(1),
-                paged_cache=self.kv_cache.bind_tasks(task_ids, total_len, self.device),
+                paged_cache=self.page_cache.bind(page_tables, total_len=total_len),
                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 ContiguousCache, KVCache
+from astrai.inference.core.cache import 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:
-    """Continuous batching loop: cleanup -> refill -> prefill -> decode (all groups)."""
+    """Four-phase continuous batching loop: cleanup -> refill -> prefill -> decode."""

    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,20 +41,19 @@ class InferenceScheduler:
        self.device = device or next(model.parameters()).device
        self.dtype = dtype or next(model.parameters()).dtype

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

-        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._page_cache = KVCache(
+            config.n_layers,
+            n_pages,
+            page_size,
+            config.n_kv_heads,
+            config.dim // config.n_heads,
+            self.device,
+            self.dtype,
+        )

        self._task_mgr = TaskManager(
            tokenizer=tokenizer,
@@ -66,32 +65,30 @@ class InferenceScheduler:
        self._executor = Executor(
            model=model,
            tokenizer=tokenizer,
-            kv_cache=self._cache,
+            page_cache=self._page_cache,
            device=self.device,
            dtype=self.dtype,
        )

-        self._stop_event = threading.Event()
-        self._loop_thread: Optional[threading.Thread] = None
+        self._running = False

    def add_task(self, prompt: str, **kwargs) -> str:
        return self._task_mgr.add_task(prompt, **kwargs)

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

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

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

                active = self._task_mgr.get_active_tasks()
                available = self._task_mgr.max_batch_size - len(active)
@@ -99,7 +96,7 @@ class InferenceScheduler:
                    candidates = self._task_mgr.pull_candidates(available)
                    failed = []
                    for task in candidates:
-                        if cache.task_alloc(task.task_id, task.prompt_ids):
+                        if self._page_cache.task_alloc(task.task_id, task.prompt_ids):
                            self._task_mgr.activate(task)
                        else:
                            failed.append(task)
@@ -111,10 +108,7 @@ class InferenceScheduler:
                    continue

                to_prefill = [
-                    t
-                    for t in self._task_mgr.get_active_tasks()
-                    if t.output_tokens == 0
-                    and cache.task_cached(t.task_id) < len(t.prompt_ids)
+                    t for t in self._task_mgr.get_active_tasks() if t.output_tokens == 0
                ]
                if to_prefill:
                    for t in to_prefill:
@@ -124,34 +118,36 @@ class InferenceScheduler:
                    for t in to_prefill:
                        key = (
                            len(t.prompt_ids),
-                            cache.task_cached(t.task_id),
+                            self._page_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 // getattr(
-                            cache, "page_size", 64
-                        )
+                        start_logical_page = start_pos // self._page_cache.page_size
                        for t in group:
-                            cache.task_record_hashes(
-                                t.task_id, t.prompt_ids, start_logical_page
+                            self._page_cache.task_record_hashes(
+                                t.task_id,
+                                t.prompt_ids,
+                                start_logical_page=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)

-                for next_pos in sorted(pos_groups.keys()):
-                    group = sorted(pos_groups[next_pos], key=lambda t: t.task_id)
+                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)

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

                    if valid:
                        next_tokens = self._executor.execute_decode(valid)
@@ -159,44 +155,41 @@ class InferenceScheduler:
                        for t, ntok in zip(valid, next_tokens):
                            t.output_ids.append(ntok)
                            t.output_tokens += 1
-                            self._task_mgr.invoke_callback(
-                                t.task_id,
-                                self._task_mgr.tokenizer.decode([ntok]),
-                            )
+                            pos = t.input_tokens + t.output_tokens
+                            self._page_cache.task_extend(t.task_id, pos)
+                            if t.stream_callback:
+                                t.stream_callback(
+                                    self._task_mgr.tokenizer.decode([ntok])
+                                )

                        for t in valid:
                            if t.is_finished(stop_ids):
-                                self._task_mgr.invoke_callback(t.task_id, STOP)
+                                if t.stream_callback:
+                                    t.stream_callback(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():
-                self._task_mgr.invoke_callback(task.task_id, STOP)
-                cache.task_free(task.task_id)
-            for task in self._task_mgr.get_waiting_tasks():
-                self._task_mgr.invoke_callback(task.task_id, STOP)
+                if task.stream_callback:
+                    task.stream_callback(STOP)
+                self._page_cache.task_free(task.task_id)
            self._task_mgr.clear_queues()
+            raise

-    def start(self):
-        if self._loop_thread is not None and self._loop_thread.is_alive():
-            return
-        self._stop_event.clear()
-        t = threading.Thread(target=self._run_generation_loop, daemon=True)
-        t.start()
-        self._loop_thread = t
+    def start(self) -> None:
+        if not self._running:
+            self._running = True
+            t = threading.Thread(target=self._run_generation_loop, daemon=True)
+            t.start()
+            self._loop_thread = t

-    def stop(self):
-        self._stop_event.set()
+    def stop(self) -> None:
+        self._running = False
        self._task_mgr.wake()
-        if self._loop_thread is not None:
+        if hasattr(self, "_loop_thread"):
            self._loop_thread.join(timeout=2.0)
-        self._loop_thread = None
        for task in self._task_mgr.get_active_tasks():
-            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():
-            self._task_mgr.invoke_callback(task.task_id, STOP)
+            self._page_cache.task_free(task.task_id)
        self._task_mgr.clear_queues()
        if torch.cuda.is_available():
            torch.cuda.empty_cache()
@@ -33,6 +33,7 @@ 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
@@ -47,6 +48,7 @@ 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:
@@ -77,7 +79,6 @@ 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()
@@ -116,13 +117,12 @@ 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,14 +134,8 @@ 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,
@@ -178,12 +172,12 @@ class TaskManager:
                to_add.append(self.waiting_queue.popleft())
        return to_add

-    def activate(self, task: Task):
+    def activate(self, task: Task) -> None:
        task.status = TaskStatus.RUNNING
        with self._lock:
            self.active_tasks.append(task)

-    def return_to_waiting(self, tasks: List[Task]):
+    def return_to_waiting(self, tasks: List[Task]) -> None:
        with self._lock:
            for task in reversed(tasks):
                self.waiting_queue.appendleft(task)
@@ -191,26 +185,18 @@ class TaskManager:
    def has_work(self) -> bool:
        return bool(self.active_tasks or self.waiting_queue)

-    def wait_for_tasks(self, timeout: float = 1.0):
-        with self._lock:
-            if self.waiting_queue or self.active_tasks:
-                return
-            self._task_event.clear()
+    def wait_for_tasks(self, timeout: float = 1.0) -> None:
+        self._task_event.clear()
        self._task_event.wait(timeout=timeout)

    def get_active_tasks(self) -> List[Task]:
        with self._lock:
            return list(self.active_tasks)

-    def get_waiting_tasks(self) -> List[Task]:
-        with self._lock:
-            return list(self.waiting_queue)
-
-    def clear_queues(self):
+    def clear_queues(self) -> None:
        with self._lock:
            self.waiting_queue.clear()
            self.active_tasks.clear()
-            self._callbacks.clear()

-    def wake(self):
+    def wake(self) -> None:
        self._task_event.set()
@@ -8,12 +8,22 @@ 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


+def _validate_sampling_params(
+    top_k: int, top_p: float, temperature: float, max_tokens: Optional[int] = None
+):
+    if not (isinstance(top_k, int) and top_k >= 0):
+        raise ValueError("top_k must be a non-negative integer")
+    if not (0.0 <= top_p <= 1.0):
+        raise ValueError("top_p must be a float between 0.0 and 1.0")
+    if not (isinstance(temperature, (int, float)) and temperature >= 0):
+        raise ValueError("temperature must be a non-negative number")
+
+
 class GenerateResult:
    """Thread-safe token accumulator for streaming and non-streaming modes."""

@@ -49,7 +59,7 @@ class GenerateResult:
    def wait(self, timeout: Optional[float] = None) -> bool:
        return self._event.wait(timeout=timeout)

-    def wait_completion(self, timeout: float = 300.0):
+    def wait_completion(self, timeout: float = 300.0) -> None:
        with self._cond:
            if not self._cond.wait_for(
                lambda: self._completed >= self._total, timeout=timeout
@@ -76,12 +86,7 @@ class GenerationRequest:
        max_tokens: Optional[int] = None,
        stream: bool = False,
    ):
-        if not (isinstance(top_k, int) and top_k >= 0):
-            raise ValueError("top_k must be a non-negative integer")
-        if not (0.0 <= top_p <= 1.0):
-            raise ValueError("top_p must be a float between 0.0 and 1.0")
-        if not (isinstance(temperature, (int, float)) and temperature > 0):
-            raise ValueError("temperature must be a positive number")
+        _validate_sampling_params(top_k, top_p, temperature, max_tokens)

        self.messages = messages
        self.top_k = top_k
@@ -102,7 +107,6 @@ 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
@@ -112,7 +116,7 @@ class InferenceEngine:
            max_batch_size=max_batch_size,
            max_seq_len=max_seq_len,
            max_prompt_len=max_prompt_len,
-            cache=cache,
+            page_size=page_size,
        )

        self.scheduler.start()
@@ -133,6 +137,7 @@ class InferenceEngine:
        top_p: float = 1.0,
        top_k: int = 50,
    ) -> Union[Generator, str, List[str]]:
+        _validate_sampling_params(top_k, top_p, temperature, max_tokens)
        is_batch = isinstance(prompt, list)
        prompts = prompt if is_batch else [prompt]

@@ -153,6 +158,7 @@ class InferenceEngine:
        top_p: float = 1.0,
        top_k: int = 50,
    ) -> AsyncGenerator[str, None]:
+        _validate_sampling_params(top_k, top_p, temperature, max_tokens)
        sync_gen = self._generate_streaming(
            [prompt], False, max_tokens, temperature, top_p, top_k
        )
@@ -283,7 +289,7 @@ class InferenceEngine:
    def get_stats(self) -> Dict[str, Any]:
        return self.scheduler.get_stats()

-    def shutdown(self):
+    def shutdown(self) -> None:
        self.scheduler.stop()
        if torch.cuda.is_available():
            torch.cuda.empty_cache()
@@ -29,7 +29,6 @@ class BaseSamplingStrategy(ABC):
        Returns:
            Transformed logits tensor.
        """
-        raise NotImplementedError


 class TemperatureStrategy(BaseSamplingStrategy):
@@ -42,15 +41,13 @@ class TemperatureStrategy(BaseSamplingStrategy):
    def __init__(self, temperature: Union[float, Tensor] = 1.0):
        self.temperature = temperature

-    def apply(self, logits: Tensor, filter_value: float = -float("inf")) -> Tensor:
+    def apply(self, logits, filter_value=-float("inf")):
        t = self.temperature
        if isinstance(t, Tensor):
-            t = t.to(logits.device, non_blocking=True).view(-1, 1)
-            t = torch.clamp(t, min=1e-8)
            if (t != 1.0).any():
-                logits = logits / t
+                logits = logits / t.to(logits.device, non_blocking=True).view(-1, 1)
        elif t != 1.0:
-            logits = logits / max(t, 1e-8)
+            logits = logits / t
        return logits


@@ -64,7 +61,7 @@ class TopKStrategy(BaseSamplingStrategy):
    def __init__(self, top_k: Union[int, Tensor] = 0):
        self.top_k = top_k

-    def apply(self, logits: Tensor, filter_value: float = -float("inf")) -> Tensor:
+    def apply(self, logits, filter_value=-float("inf")):
        tk = self.top_k
        if isinstance(tk, Tensor):
            tk = tk.to(logits.device, non_blocking=True).long().clamp(min=0)
@@ -101,9 +98,7 @@ class TopPStrategy(BaseSamplingStrategy):
    def __init__(self, top_p: Union[float, Tensor] = 1.0):
        self.top_p = top_p

-    def _apply(
-        self, logits: Tensor, top_p: Union[float, Tensor], filter_value: float
-    ) -> Tensor:
+    def _apply(self, logits, top_p, filter_value):
        sorted_logits, sorted_indices = torch.sort(logits, descending=True, dim=-1)
        cum_probs = torch.cumsum(torch.softmax(sorted_logits, dim=-1), dim=-1)
        remove = cum_probs > top_p
@@ -114,7 +109,7 @@ class TopPStrategy(BaseSamplingStrategy):
        logits[mask] = filter_value
        return logits

-    def apply(self, logits: Tensor, filter_value: float = -float("inf")) -> Tensor:
+    def apply(self, logits, filter_value=-float("inf")):
        tp = self.top_p
        if isinstance(tp, Tensor):
            tp = tp.to(logits.device, non_blocking=True)
@@ -145,7 +140,7 @@ class SamplingPipeline(BaseSamplingStrategy):
    def __init__(self, strategies: List[BaseSamplingStrategy]):
        self.strategies = strategies

-    def apply(self, logits: Tensor, filter_value: float = -float("inf")) -> Tensor:
+    def apply(self, logits, filter_value=-float("inf")):
        for strategy in self.strategies:
            logits = strategy.apply(logits, filter_value)
        return logits
@@ -2,13 +2,6 @@ from astrai.model.automodel import AutoModel
 from astrai.model.components.attention import GQA
 from astrai.model.components.decoder_block import DecoderBlock
 from astrai.model.components.linear import Linear
-from astrai.model.components.lora import (
-    LoRAConfig,
-    inject_lora,
-    load_lora,
-    merge_lora,
-    save_lora,
-)
 from astrai.model.components.mlp import MLP
 from astrai.model.components.norm import RMSNorm
 from astrai.model.encoder import EmbeddingEncoder
@@ -25,10 +18,4 @@ __all__ = [
    "AutoRegressiveLM",
    "EmbeddingEncoder",
    "AutoModel",
-    # LoRA
-    "LoRAConfig",
-    "inject_lora",
-    "merge_lora",
-    "save_lora",
-    "load_lora",
 ]
@@ -2,24 +2,21 @@
 AutoModel base class for model loading and saving.
 """

+import json
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Self, Union

+import safetensors.torch as st
 import torch.nn as nn

 from astrai.config.model_config import BaseModelConfig, ConfigFactory
 from astrai.factory import BaseFactory
-from astrai.serialization import load_model_config, load_model_weights, save_model


@contextmanager
 def _disable_random_init(enable: bool = True):
-    if not enable:
-        yield
-        return
-
-    names = (
+    init_functions = [
        "xavier_normal_",
        "xavier_uniform_",
        "kaiming_normal_",
@@ -29,15 +26,18 @@ def _disable_random_init(enable: bool = True):
        "constant_",
        "normal_",
        "uniform_",
-    )
-    orig = {n: getattr(nn.init, n) for n in names if hasattr(nn.init, n)}
-    for n in orig:
-        setattr(nn.init, n, lambda *a, **kw: None)
+    ]
+    original_funcs = {}
+    for name in init_functions:
+        if enable and hasattr(nn.init, name):
+            original_funcs[name] = getattr(nn.init, name)
+            setattr(nn.init, name, lambda *args, **kwargs: None)
    try:
        yield
    finally:
-        for n, fn in orig.items():
-            setattr(nn.init, n, fn)
+        if enable:
+            for name, orig_func in original_funcs.items():
+                setattr(nn.init, name, orig_func)


 class AutoModel(BaseFactory["AutoModel"], nn.Module):
@@ -60,22 +60,25 @@ class AutoModel(BaseFactory["AutoModel"], nn.Module):

        model_path = Path(path)

+        # Load config
        config_path = model_path / "config.json"
-        if not config_path.exists():
+        if config_path.exists():
+            with open(config_path, "r") as f:
+                raw = json.load(f)
+            config = ConfigFactory.load(raw)
+            model_type = config.model_type or "autoregressive_lm"
+        else:
            raise FileNotFoundError(f"Config file not found: {config_path}")

-        raw = load_model_config(str(model_path))
-        config = ConfigFactory.load(raw)
-        model_type = config.model_type or "autoregressive_lm"
-
        actual_cls = AutoModel.get_component_class(model_type)

        with _disable_random_init(enable=disable_random_init):
            model = actual_cls(config)

+        # Load weights
        weights_path = model_path / "model.safetensors"
        if weights_path.exists():
-            state_dict = load_model_weights(str(model_path))
+            state_dict = st.load_file(str(weights_path))
            model.load_state_dict(state_dict, strict=strict)

        return model
@@ -83,12 +86,15 @@ class AutoModel(BaseFactory["AutoModel"], nn.Module):
    def save_pretrained(
        self,
        save_directory: Union[str, Path],
-    ):
-        save_model(
-            config=self.config.to_dict(),
-            state_dict=self.state_dict(),
-            save_directory=str(save_directory),
-        )
+    ) -> None:
+        save_path = Path(save_directory)
+        save_path.mkdir(parents=True, exist_ok=True)
+
+        # Save config
+        self.config.to_file(str(save_path / "config.json"))
+
+        # Save weights
+        st.save_file(self.state_dict(), str(save_path / "model.safetensors"))

    def to(self, *args, **kwargs) -> Self:
        """Move model to device/dtype."""
@@ -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 CacheView
+from astrai.inference.core.cache import KvcacheView
 from astrai.model.components.linear import Linear
 from astrai.model.components.norm import RMSNorm
 from astrai.model.components.rope import apply_rotary_emb
@@ -24,7 +24,9 @@ def repeat_kv(x: Tensor, n_rep: int) -> Tensor:


 class AttnFactory(BaseFactory[nn.Module]):
-    pass
+    @classmethod
+    def create(cls, attn_type: str, **kwargs) -> nn.Module:
+        return super().create(attn_type, **kwargs)


@AttnFactory.register("gqa")
@@ -38,7 +40,6 @@ class GQA(nn.Module):
        norm_eps: float,
        use_gated_attention: bool,
        layer_id: int,
-        n_layers: int = 1,
    ):
        super().__init__()
        assert dim % n_heads == 0
@@ -56,7 +57,7 @@ class GQA(nn.Module):
        self.q_proj = Linear(dim, n_heads * self.head_dim)
        self.k_proj = Linear(dim, n_kv_heads * self.head_dim)
        self.v_proj = Linear(dim, n_kv_heads * self.head_dim)
-        self.o_proj = Linear(dim, dim, init_std=0.02 / (2 * n_layers) ** 0.5)
+        self.o_proj = Linear(dim, dim)

        if self.use_qk_norm:
            self.q_norm = RMSNorm(self.head_dim, norm_eps)
@@ -75,7 +76,7 @@ class GQA(nn.Module):
        x: Tensor,
        rotary_emb: Tensor,
        attn_mask: Tensor = None,
-        paged_cache: Optional[CacheView] = None,
+        paged_cache: Optional[KvcacheView] = None,
    ) -> Tensor:
        is_causal = attn_mask is None

@@ -122,7 +123,6 @@ class MLA(nn.Module):
        use_qk_norm: bool,
        use_gated_attention: bool,
        layer_id: int,
-        n_layers: int = 1,
    ):
        super().__init__()
        self.dim = dim
@@ -150,9 +150,7 @@ class MLA(nn.Module):
            n_kv_heads * (2 * self.head_dim),
        )

-        self.o_proj = Linear(
-            dim, dim, bias=False, init_std=0.02 / (2 * n_layers) ** 0.5
-        )
+        self.o_proj = Linear(dim, dim, bias=False)

        if use_gated_attention:
            self.gate = Linear(dim, dim, bias=False)
@@ -162,7 +160,7 @@ class MLA(nn.Module):
        x: Tensor,
        rotary_emb: Tensor,
        attn_mask: Tensor = None,
-        paged_cache: Optional[CacheView] = None,
+        paged_cache: Optional[KvcacheView] = None,
    ) -> Tensor:
        bsz, seq_len, _ = x.size()
        is_causal = attn_mask is None
@@ -1,31 +1,51 @@
-from dataclasses import asdict
 from typing import Optional

 import torch.nn as nn
 from torch import Tensor

-from astrai.inference.core.cache import CacheView
+from astrai.inference.core.cache import KvcacheView
 from astrai.model.components.attention import AttnFactory
 from astrai.model.components.mlp import FFNFactory
 from astrai.model.components.norm import RMSNorm


 class DecoderBlock(nn.Module):
-    def __init__(self, config, layer_id: int):
+    def __init__(
+        self,
+        dim: int,
+        n_heads: int,
+        dim_ffn: int,
+        n_kv_heads: int,
+        norm_eps: float,
+        use_qk_norm: bool,
+        use_gated_attention: bool,
+        layer_id: int,
+        attn_type: str = "gqa",
+        ffn_type: str = "mlp",
+        **kwargs,
+    ):
        super().__init__()
-        cfg = asdict(config)
-        cfg["down_init_std"] = 0.02 / (2 * config.n_layers) ** 0.5
-        self.attention = AttnFactory.create(config.attn_type, **cfg, layer_id=layer_id)
-        self.input_norm = RMSNorm(config.dim, config.norm_eps)
-        self.post_attention_norm = RMSNorm(config.dim, config.norm_eps)
-        self.mlp = FFNFactory.create(config.ffn_type, **cfg)
+        self.attention = AttnFactory.create(
+            attn_type,
+            dim=dim,
+            n_heads=n_heads,
+            n_kv_heads=n_kv_heads,
+            use_qk_norm=use_qk_norm,
+            norm_eps=norm_eps,
+            use_gated_attention=use_gated_attention,
+            layer_id=layer_id,
+            **kwargs,
+        )
+        self.input_norm = RMSNorm(dim, norm_eps)
+        self.post_attention_norm = RMSNorm(dim, norm_eps)
+        self.mlp = FFNFactory.create(ffn_type, dim, dim_ffn, **kwargs)

    def forward(
        self,
        x: Tensor,
        rotary_emb: Tensor,
        attention_mask: Optional[Tensor] = None,
-        paged_cache: Optional[CacheView] = None,
+        paged_cache: Optional[KvcacheView] = None,
    ) -> Tensor:
        attn_output = self.attention(
            self.input_norm(x),
@@ -1,5 +1,3 @@
-import math
-
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
@@ -7,20 +5,12 @@ from torch import Tensor


 class Embedding(nn.Module):
-    def __init__(self, vocab_size: int, embedding_dim: int, neftune_alpha: float = 0.0):
+    def __init__(self, vocab_size: int, embedding_dim: int):
        super().__init__()
        self.weight = nn.Parameter(torch.empty((vocab_size, embedding_dim)))
-        self.neftune_noise_alpha = neftune_alpha
-
-    def set_neftune_alpha(self, alpha: float):
-        self.neftune_noise_alpha = alpha

    def reset_parameters(self):
        nn.init.normal_(self.weight, mean=0.0, std=0.02)

    def forward(self, x: Tensor) -> Tensor:
-        out = F.embedding(x, self.weight)
-        if self.training and self.neftune_noise_alpha > 0.0:
-            eps = self.neftune_noise_alpha / math.sqrt(out.size(1))
-            out = out + eps * torch.randn_like(out)
-        return out
+        return F.embedding(x, self.weight)
@@ -5,16 +5,13 @@ from torch import Tensor


 class Linear(nn.Module):
-    def __init__(
-        self, in_dim: int, out_dim: int, bias: bool = False, init_std: float = 0.02
-    ):
+    def __init__(self, in_dim: int, out_dim: int, bias: bool = False):
        super().__init__()
        self.weight = nn.Parameter(torch.empty((out_dim, in_dim)))
        self.bias = nn.Parameter(torch.zeros(out_dim)) if bias else None
-        self.init_std = init_std

    def reset_parameters(self):
-        nn.init.normal_(self.weight, mean=0.0, std=self.init_std)
+        nn.init.kaiming_uniform_(self.weight, a=5**0.5)
        if self.bias is not None:
            fan_in, _ = nn.init._calculate_fan_in_and_fan_out(self.weight)
            bound = 1 / (fan_in**0.5)
@@ -1,194 +0,0 @@
-import logging
-from dataclasses import asdict, dataclass
-from pathlib import Path
-from typing import Optional, Set
-
-import torch
-import torch.nn as nn
-import torch.nn.functional as F
-
-from astrai.model.components.linear import Linear
-from astrai.serialization import (
-    load_json,
-    load_safetensors,
-    save_json,
-    save_safetensors,
-)
-
-logger = logging.getLogger(__name__)
-
-TARGET_MODULES_ATTN = {"q_proj", "k_proj", "v_proj", "o_proj"}
-TARGET_MODULES_FFN = {"up", "gate", "down"}
-
-
-@dataclass
-class LoRAConfig:
-    r: int = 16
-    alpha: int = 32
-    target_modules: tuple = ("q_proj", "v_proj")
-
-
-class LoRALinear(nn.Module):
-    def __init__(self, base: Linear, r: int = 16, alpha: int = 32):
-        super().__init__()
-        self.register_parameter("weight", base.weight)
-        self.weight.requires_grad_(False)
-        self.bias = base.bias
-        if self.bias is not None:
-            self.bias.requires_grad_(False)
-
-        self.r = r
-        self.scaling = alpha / r
-        self.lora_A = nn.Parameter(torch.randn(r, self.weight.shape[1]) / r)
-        self.lora_B = nn.Parameter(torch.zeros(self.weight.shape[0], r))
-        self._merged = False
-
-    def forward(self, x):
-        out = F.linear(x, self.weight, self.bias)
-        if not self._merged:
-            out += (F.linear(x, self.lora_A) @ self.lora_B.T) * self.scaling
-        return out
-
-    def merge(self):
-        if self._merged:
-            return
-        self.weight.data += (self.lora_B @ self.lora_A) * self.scaling
-        self._merged = True
-        del self.lora_A
-        del self.lora_B
-
-
-def _collect_lora_info(model: nn.Module) -> dict:
-    names = {}
-    for n, m in model.named_modules():
-        if isinstance(m, Linear):
-            _, _, child = n.rpartition(".")
-            names.setdefault(child, []).append(n)
-    return names
-
-
-def _get_lora_count(model: nn.Module) -> int:
-    return sum(1 for m in model.modules() if isinstance(m, LoRALinear))
-
-
-def inject_lora(
-    model: nn.Module,
-    r: int = 16,
-    alpha: int = 32,
-    target_modules: Optional[Set[str]] = None,
-) -> LoRAConfig:
-    if target_modules is None:
-        target_modules = TARGET_MODULES_ATTN
-
-    available = _collect_lora_info(model)
-    injected = 0
-
-    for name, module in list(model.named_modules()):
-        if not isinstance(module, Linear):
-            continue
-        parent_name, _, child_name = name.rpartition(".")
-        if child_name not in target_modules:
-            continue
-        parent = model.get_submodule(parent_name) if parent_name else model
-        setattr(parent, child_name, LoRALinear(module, r=r, alpha=alpha))
-        injected += 1
-
-    if injected == 0:
-        logger.warning(
-            "No LoRA layers injected. Available Linear child names: %s. "
-            "target_modules: %s. Check model type and target_modules.",
-            sorted(available),
-            sorted(target_modules),
-        )
-    else:
-        logger.info("LoRA injected: %d layers (r=%d, alpha=%d)", injected, r, alpha)
-
-    return LoRAConfig(r=r, alpha=alpha, target_modules=tuple(target_modules))
-
-
-def merge_lora(model: nn.Module):
-    n = 0
-    for module in model.modules():
-        if isinstance(module, LoRALinear):
-            module.merge()
-            n += 1
-    if n == 0:
-        logger.warning("No LoRA layers to merge.")
-    else:
-        logger.info("Merged %d LoRA layers", n)
-
-
-def save_lora(model: nn.Module, save_dir: str, config: LoRAConfig):
-    lora_sd = {
-        k: v
-        for k, v in model.state_dict().items()
-        if k.endswith((".lora_A", ".lora_B"))
-    }
-    if not lora_sd:
-        raise RuntimeError(
-            "No LoRA parameters found in model. "
-            "The model may not have been injected or was already merged."
-        )
-
-    path = Path(save_dir)
-    path.mkdir(parents=True, exist_ok=True)
-    save_safetensors(lora_sd, path / "adapter_model.safetensors")
-    save_json(asdict(config), path / "adapter_config.json")
-    logger.info("LoRA adapter saved to %s (%d keys)", save_dir, len(lora_sd))
-
-
-def load_lora(model: nn.Module, load_dir: str) -> LoRAConfig:
-    path = Path(load_dir)
-    raw = load_json(path / "adapter_config.json")
-    config = LoRAConfig(
-        r=raw["r"], alpha=raw["alpha"], target_modules=tuple(raw["target_modules"])
-    )
-
-    existing = _get_lora_count(model)
-    if existing > 0:
-        logger.warning(
-            "Model already has %d LoRA layers. Skipping injection, "
-            "loading weights onto existing layers only.",
-            existing,
-        )
-    else:
-        inject_lora(
-            model,
-            r=config.r,
-            alpha=config.alpha,
-            target_modules=set(config.target_modules),
-        )
-
-    weights = load_safetensors(path / "adapter_model.safetensors")
-    try:
-        missing, unexpected = model.load_state_dict(weights, strict=False)
-    except RuntimeError as e:
-        msg = str(e)
-        if "size mismatch" in msg:
-            raise RuntimeError(
-                f"LoRA weight shapes do not match the model. "
-                f"The adapter config (r={config.r}) may not match the injected layers. "
-                f"Original error: {msg}"
-            ) from e
-        raise
-
-    injected = _get_lora_count(model)
-    if injected == 0:
-        raise RuntimeError(
-            "No LoRA layers found after loading. "
-            "Inject LoRA before calling load_lora, or check the adapter config."
-        )
-
-    if missing:
-        lora_missing = [k for k in missing if "lora" in k]
-        if lora_missing:
-            raise RuntimeError(
-                f"LoRA weight keys not found in model: {lora_missing}. "
-                f"The adapter config (r={config.r}) may not match the model."
-            )
-        logger.debug("LoRA load: %d missing base-weight keys (expected)", len(missing))
-    if unexpected:
-        logger.warning("LoRA load: %d unexpected keys", len(unexpected))
-
-    logger.info("LoRA adapter loaded from %s", load_dir)
-    return config
@@ -8,16 +8,18 @@ from astrai.model.components.linear import Linear


 class FFNFactory(BaseFactory[nn.Module]):
-    pass
+    @classmethod
+    def create(cls, ffn_type: str, dim: int, dim_ffn: int, **kwargs) -> nn.Module:
+        return super().create(ffn_type, dim, dim_ffn, **kwargs)


@FFNFactory.register("mlp")
 class MLP(nn.Module):
-    def __init__(self, dim: int, dim_ffn: int, down_init_std: float = 0.02):
+    def __init__(self, dim: int, dim_ffn: int):
        super().__init__()
        self.up = Linear(dim, dim_ffn)
        self.gate = Linear(dim, dim_ffn)
-        self.down = Linear(dim_ffn, dim, init_std=down_init_std)
+        self.down = Linear(dim_ffn, dim)

    def forward(self, x: Tensor) -> Tensor:
        gated = self.up(x) * F.silu(self.gate(x))
@@ -35,7 +37,6 @@ class DeepSeekMoE(nn.Module):
        n_shared_experts: int = 1,
        n_activated_experts: int = 2,
        topk_method: str = "greedy",
-        n_layers: int = 1,
    ):
        super().__init__()
        self.dim = dim
@@ -45,20 +46,12 @@ class DeepSeekMoE(nn.Module):
        self.topk_method = topk_method

        self.router = Linear(dim, n_routed_experts, bias=False)
-        moe_scale = 1 / max(n_shared_experts, 1) + 1 / n_activated_experts
-        down_init_std = 0.02 / (2 * n_layers * moe_scale) ** 0.5

        self.shared_experts = nn.ModuleList(
-            [
-                MLP(dim, dim_ffn, down_init_std=down_init_std)
-                for _ in range(n_shared_experts)
-            ]
+            [MLP(dim, dim_ffn) for _ in range(n_shared_experts)]
        )
        self.routed_experts = nn.ModuleList(
-            [
-                MLP(dim, dim_ffn, down_init_std=down_init_std)
-                for _ in range(n_routed_experts)
-            ]
+            [MLP(dim, dim_ffn) for _ in range(n_routed_experts)]
        )

    def forward(self, x: Tensor) -> Tensor:
@@ -1,4 +1,4 @@
-from typing import Dict, Optional
+from typing import Optional

 import torch
 import torch.nn as nn
@@ -19,10 +19,6 @@ def get_rotary_emb(
    return torch.complex(cos, sin)


-def ntk_base(base: float, dim: int, factor: float) -> float:
-    return base * (factor ** (dim / (dim - 2)))
-
-
 def apply_rotary_emb(x: torch.Tensor, freqs_cis: Tensor) -> Tensor:
    dtype = x.dtype
    x_ = x.float().reshape(*x.shape[:-1], -1, 2)
@@ -34,25 +30,11 @@ def apply_rotary_emb(x: torch.Tensor, freqs_cis: Tensor) -> Tensor:


 class RotaryEmbedding(nn.Module):
-    def __init__(
-        self,
-        dim: int,
-        max_len: int,
-        base: float = 10000,
-        rope_scaling: Optional[Dict] = None,
-    ):
+    def __init__(self, dim: int, max_len: int, base: float = 10000):
        super().__init__()
        self.dim = dim
        self.max_len = max_len
        self.base = base
-        self.rope_scaling = rope_scaling
-
-        if rope_scaling is not None:
-            scaling_type = rope_scaling.get("type", "ntk")
-            factor = rope_scaling.get("factor", 1.0)
-            if scaling_type == "ntk":
-                self.base = ntk_base(base, dim, factor)
-
        self._set_rotary_buffer(self.max_len)

    def _set_rotary_buffer(self, max_len: int):
@@ -20,15 +20,23 @@ class EmbeddingEncoder(AutoModel):
        self.config = config
        rope_dim = config.dim // config.n_heads
        rope_base = config.rope_theta if config.rope_theta is not None else 10000
-        self.rotary_embedding = RotaryEmbedding(
-            rope_dim, config.max_len, rope_base, rope_scaling=config.rope_scaling
-        )
-        self.embed_tokens = Embedding(
-            config.vocab_size, config.dim, neftune_alpha=config.neftune_alpha
-        )
+        self.rotary_embedding = RotaryEmbedding(rope_dim, config.max_len, rope_base)
+        self.embed_tokens = Embedding(config.vocab_size, config.dim)

        self.layers = nn.ModuleList(
-            [DecoderBlock(config, layer_id) for layer_id in range(config.n_layers)]
+            [
+                DecoderBlock(
+                    config.dim,
+                    config.n_heads,
+                    config.dim_ffn,
+                    config.n_kv_heads,
+                    config.norm_eps,
+                    config.use_qk_norm,
+                    config.use_gated_attention,
+                    layer_id,
+                )
+                for layer_id in range(config.n_layers)
+            ]
        )

        self.norm = RMSNorm(config.dim, config.norm_eps)
@@ -58,6 +66,9 @@ class EmbeddingEncoder(AutoModel):

        x = self.embed_tokens(input_ids)

+        if position_ids is None:
+            position_ids = torch.arange(S, device=x.device).unsqueeze(0).expand(B, -1)
+
        rotary_emb = self.rotary_embedding(x, position_ids)
        attn_mask = process_attention_mask(x, position_ids, input_mask, is_causal=False)

@@ -1,11 +1,11 @@
-from typing import Any, Dict, Mapping, Optional
+from typing import Any, Mapping, Optional

 import torch
 import torch.nn as nn
 from torch import Tensor

 from astrai.config.model_config import AutoRegressiveLMConfig
-from astrai.inference.core.cache import CacheView
+from astrai.inference.core.cache import KvcacheView
 from astrai.model.automodel import AutoModel
 from astrai.model.components.decoder_block import DecoderBlock
 from astrai.model.components.embedding import Embedding
@@ -26,21 +26,24 @@ def process_attention_mask(
        return input_mask

    device = input_tensor.device
-    B = input_tensor.size(0)
+    dtype = input_tensor.dtype
+    B, S = input_tensor.size()[:2]
    T = position_ids.max().item() + 1

    if input_mask is None:
        if position_ids.min().item() == 0 and is_causal:
            return None
-        attend = torch.ones(B, 1, T, dtype=torch.bool, device=device)
+        pad = torch.ones(B, T, dtype=torch.bool, device=device)
    else:
-        attend = input_mask[:, :T].to(device=device, dtype=torch.bool).unsqueeze(1)
+        pad = input_mask[:, :T].to(device=device, dtype=torch.bool)

+    attend = pad.view(B, 1, T).expand(B, S, T).clone()
    if is_causal:
-        causal = position_ids.unsqueeze(-1) >= torch.arange(T, device=device)
-        attend = attend & causal
+        attend &= position_ids.unsqueeze(-1) >= torch.arange(T, device=device)

-    return attend.unsqueeze(1)
+    return torch.full(
+        (B, 1, S, T), -torch.finfo(dtype).max / 2, dtype=dtype, device=device
+    ).masked_fill_(attend.unsqueeze(1), 0.0)


@AutoModel.register("autoregressive_lm")
@@ -56,15 +59,32 @@ class AutoRegressiveLM(AutoModel):
            else config.dim // config.n_heads
        )
        rope_base = config.rope_theta if config.rope_theta is not None else 10000
-        self.rotary_embedding = RotaryEmbedding(
-            rope_dim, config.max_len, rope_base, rope_scaling=config.rope_scaling
-        )
-        self.embed_tokens = Embedding(
-            config.vocab_size, config.dim, neftune_alpha=config.neftune_alpha
-        )
+        self.rotary_embedding = RotaryEmbedding(rope_dim, config.max_len, rope_base)
+        self.embed_tokens = Embedding(config.vocab_size, config.dim)

        self.layers = nn.ModuleList(
-            [DecoderBlock(config, layer_id) for layer_id in range(config.n_layers)]
+            [
+                DecoderBlock(
+                    config.dim,
+                    config.n_heads,
+                    config.dim_ffn,
+                    config.n_kv_heads,
+                    config.norm_eps,
+                    config.use_qk_norm,
+                    config.use_gated_attention,
+                    layer_id,
+                    attn_type=config.attn_type,
+                    ffn_type=config.ffn_type,
+                    n_routed_experts=config.n_routed_experts,
+                    n_shared_experts=config.n_shared_experts,
+                    n_activated_experts=config.n_activated_experts,
+                    topk_method=config.topk_method,
+                    kv_lora_rank=config.kv_lora_rank,
+                    qk_nope_head_dim=config.qk_nope_head_dim,
+                    qk_rope_head_dim=config.qk_rope_head_dim,
+                )
+                for layer_id in range(config.n_layers)
+            ]
        )

        self.norm = RMSNorm(config.dim, config.norm_eps)
@@ -112,9 +132,9 @@ class AutoRegressiveLM(AutoModel):
        self,
        input_ids: Tensor,
        input_mask: Optional[Tensor] = None,
-        paged_cache: Optional[CacheView] = None,
+        paged_cache: Optional[KvcacheView] = None,
        position_ids: Optional[Tensor] = None,
-    ) -> Dict[str, Tensor]:
+    ) -> Tensor:
        assert input_ids.ndim == 2

        x = self.embed_tokens(input_ids)
@@ -1,13 +1,3 @@
-from astrai.parallel.executor import (
-    AccumOptimizer,
-    AccumScheduler,
-    BaseExecutor,
-    DDPExecutor,
-    ExecutorFactory,
-    FSDPExecutor,
-    GradientState,
-    NoneExecutor,
-)
 from astrai.parallel.module import ColumnParallelLinear, RowParallelLinear
 from astrai.parallel.setup import (
    get_current_device,
@@ -27,12 +17,4 @@ __all__ = [
    "spawn_parallel_fn",
    "RowParallelLinear",
    "ColumnParallelLinear",
-    "ExecutorFactory",
-    "BaseExecutor",
-    "GradientState",
-    "AccumOptimizer",
-    "AccumScheduler",
-    "NoneExecutor",
-    "DDPExecutor",
-    "FSDPExecutor",
 ]
@@ -1,286 +0,0 @@
-"""Unified training executor — parallel strategy + gradient accumulation."""
-
-import contextlib
-import logging
-import os
-from contextlib import contextmanager
-from typing import Optional, Tuple
-
-import torch
-import torch.nn as nn
-from torch.distributed.fsdp import FullStateDictConfig, StateDictType
-from torch.distributed.fsdp import FullyShardedDataParallel as FSDP
-from torch.nn.parallel import DistributedDataParallel as DDP
-from torch.optim import Optimizer
-from torch.optim.lr_scheduler import LRScheduler
-from torch.utils.data import DataLoader
-
-from astrai.factory import BaseFactory
-from astrai.parallel.setup import get_rank, get_world_size
-
-logger = logging.getLogger(__name__)
-
-
-class GradientState:
-    def __init__(self, grad_accum_steps: int = 1):
-        self.num_steps = max(grad_accum_steps, 1)
-        self._step: int = 0
-        self._sync_gradients: bool = True
-
-    @property
-    def sync_gradients(self) -> bool:
-        return self._sync_gradients
-
-    def _do_sync(self):
-        self._step += 1
-        self._sync_gradients = self._step % self.num_steps == 0
-
-
-class AccumOptimizer:
-    def __init__(self, optimizer: Optimizer, gradient_state: GradientState):
-        self.optimizer = optimizer
-        self.gradient_state = gradient_state
-
-    def step(self, closure=None):
-        if self.gradient_state.sync_gradients:
-            self.optimizer.step(closure)
-
-    def zero_grad(self):
-        if self.gradient_state.sync_gradients:
-            self.optimizer.zero_grad()
-
-    @property
-    def param_groups(self):
-        return self.optimizer.param_groups
-
-    def state_dict(self):
-        return self.optimizer.state_dict()
-
-    def load_state_dict(self, d):
-        self.optimizer.load_state_dict(d)
-
-
-class AccumScheduler:
-    def __init__(self, scheduler: LRScheduler, gradient_state: GradientState):
-        self.scheduler = scheduler
-        self.gradient_state = gradient_state
-
-    def step(self):
-        if self.gradient_state.sync_gradients:
-            self.scheduler.step()
-
-    def state_dict(self):
-        return self.scheduler.state_dict()
-
-    def load_state_dict(self, d):
-        self.scheduler.load_state_dict(d)
-
-    def get_last_lr(self):
-        return self.scheduler.get_last_lr()
-
-
-class BaseExecutor:
-    def __init__(self, grad_accum_steps: int = 1):
-        self.gradient_state = GradientState(grad_accum_steps)
-
-    def prepare(
-        self,
-        model: nn.Module,
-        optimizer: Optional[Optimizer] = None,
-        dataloader: Optional[DataLoader] = None,
-        scheduler: Optional[LRScheduler] = None,
-    ) -> Tuple[
-        nn.Module, Optional[Optimizer], Optional[DataLoader], Optional[LRScheduler]
-    ]:
-        model = self._prepare_model(model)
-        if optimizer is not None:
-            optimizer = AccumOptimizer(optimizer, self.gradient_state)
-        if scheduler is not None:
-            scheduler = AccumScheduler(scheduler, self.gradient_state)
-        return model, optimizer, dataloader, scheduler
-
-    def _prepare_model(self, model: nn.Module) -> nn.Module:
-        return model
-
-    def _no_sync(self, model: nn.Module):
-        return contextlib.nullcontext()
-
-    @contextmanager
-    def accumulate(self, model: nn.Module):
-        self.gradient_state._do_sync()
-        if not self.gradient_state.sync_gradients:
-            with self._no_sync(model):
-                yield
-        else:
-            yield
-
-    def backward(self, loss: torch.Tensor):
-        loss.backward()
-
-    def unwrap_model(self, model: nn.Module):
-        return model.state_dict()
-
-    @property
-    def use_distributed(self) -> bool:
-        return get_world_size() > 1
-
-    @property
-    def sync_gradients(self) -> bool:
-        return self.gradient_state.sync_gradients
-
-    @property
-    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
-
-
-@ExecutorFactory.register("none")
-class NoneExecutor(BaseExecutor):
-    pass
-
-
-@ExecutorFactory.register("ddp")
-class DDPExecutor(BaseExecutor):
-    def __init__(
-        self,
-        grad_accum_steps: int = 1,
-        dim: int = 0,
-        broadcast_buffers: bool = True,
-        init_sync: bool = True,
-        process_group=None,
-        bucket_cap_mb: int = 25,
-        find_unused_parameters: bool = False,
-        check_reduction: bool = False,
-        gradient_as_bucket_view: bool = False,
-        static_graph: bool = False,
-        delay_all_reduce_named_params=None,
-        param_to_hook_all_reduce=None,
-        mixed_precision=None,
-        device_mesh=None,
-    ):
-        super().__init__(grad_accum_steps=grad_accum_steps)
-        self._ddp_kwargs = dict(
-            dim=dim,
-            broadcast_buffers=broadcast_buffers,
-            init_sync=init_sync,
-            process_group=process_group,
-            bucket_cap_mb=bucket_cap_mb,
-            find_unused_parameters=find_unused_parameters,
-            check_reduction=check_reduction,
-            gradient_as_bucket_view=gradient_as_bucket_view,
-            static_graph=static_graph,
-            delay_all_reduce_named_params=delay_all_reduce_named_params,
-            param_to_hook_all_reduce=param_to_hook_all_reduce,
-            mixed_precision=mixed_precision,
-            device_mesh=device_mesh,
-        )
-
-    def _prepare_model(self, model: nn.Module) -> nn.Module:
-        if not self.use_distributed:
-            logger.warning("DDP backend selected but world_size=1, model not wrapped")
-            return model
-        local_rank = int(os.environ.get("LOCAL_RANK", get_rank()))
-        model = DDP(
-            model,
-            device_ids=[local_rank],
-            output_device=local_rank,
-            **self._ddp_kwargs,
-        )
-        logger.info("Model wrapped with DDP (world_size=%d)", get_world_size())
-        return model
-
-    def _no_sync(self, model: nn.Module):
-        if isinstance(model, DDP):
-            return model.no_sync()
-        return contextlib.nullcontext()
-
-    def unwrap_model(self, model: nn.Module):
-        if isinstance(model, DDP):
-            return model.module.state_dict()
-        return model.state_dict()
-
-
-@ExecutorFactory.register("fsdp")
-class FSDPExecutor(BaseExecutor):
-    def __init__(
-        self,
-        grad_accum_steps: int = 1,
-        process_group=None,
-        sharding_strategy=None,
-        cpu_offload=None,
-        auto_wrap_policy=None,
-        backward_prefetch=None,
-        mixed_precision=None,
-        ignored_modules=None,
-        param_init_fn=None,
-        sync_module_states: bool = False,
-        forward_prefetch: bool = False,
-        limit_all_gathers: bool = True,
-        ignored_states=None,
-        device_mesh=None,
-    ):
-        super().__init__(grad_accum_steps=grad_accum_steps)
-        self._fsdp_kwargs = {
-            k: v
-            for k, v in dict(
-                process_group=process_group,
-                sharding_strategy=sharding_strategy,
-                cpu_offload=cpu_offload,
-                auto_wrap_policy=auto_wrap_policy,
-                backward_prefetch=backward_prefetch,
-                mixed_precision=mixed_precision,
-                ignored_modules=ignored_modules,
-                param_init_fn=param_init_fn,
-                sync_module_states=sync_module_states,
-                forward_prefetch=forward_prefetch,
-                limit_all_gathers=limit_all_gathers,
-                use_orig_params=True,
-                ignored_states=ignored_states,
-                device_mesh=device_mesh,
-            ).items()
-            if v is not None
-        }
-        self._original_model: Optional[nn.Module] = None
-
-    def _prepare_model(self, model: nn.Module) -> nn.Module:
-        if not self.use_distributed:
-            logger.warning("FSDP backend selected but world_size=1, model not wrapped")
-            return model
-        self._original_model = model
-        device_id = torch.device("cuda", get_rank())
-        model = FSDP(model, device_id=device_id, **self._fsdp_kwargs)
-        logger.info("Model wrapped with FSDP (world_size=%d)", get_world_size())
-        return model
-
-    def _no_sync(self, model: nn.Module):
-        if isinstance(model, FSDP):
-            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(
-                model,
-                StateDictType.FULL_STATE_DICT,
-                FullStateDictConfig(offload_to_cpu=True, rank0_only=False),
-            ):
-                return model.state_dict()
-
-        return model.state_dict()
@@ -1,5 +1,4 @@
 import os
-from abc import ABC, abstractmethod
 from contextlib import contextmanager
 from functools import wraps
 from typing import Callable
@@ -31,7 +30,6 @@ def get_rank() -> int:
 def setup_parallel(
    rank: int,
    world_size: int,
-    local_rank: int,
    backend: str = "nccl",
    master_addr: str = "localhost",
    master_port: str = "29500",
@@ -43,26 +41,20 @@ def setup_parallel(
        return

    if world_size <= 1:
-        device_id = torch.device(device_type, local_rank)
-        os.environ["LOCAL_RANK"] = str(local_rank)
-        os.environ["WORLD_SIZE"] = "1"
-        os.environ["LOCAL_DEVICE"] = str(device_id)
        yield None
        return

-    device_id = torch.device(device_type, local_rank)
+    device_id = torch.device(device_type, rank)

    os.environ["MASTER_ADDR"] = master_addr
    os.environ["MASTER_PORT"] = master_port
-    os.environ["LOCAL_RANK"] = str(local_rank)
+    os.environ["LOCAL_RANK"] = str(rank)
    os.environ["WORLD_SIZE"] = str(world_size)
    os.environ["LOCAL_DEVICE"] = str(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)
+    dist.init_process_group(
+        rank=rank, world_size=world_size, backend=backend, device_id=device_id
+    )

    try:
        if backend == "nccl" and torch.cuda.is_available():
@@ -98,7 +90,7 @@ def only_on_rank(rank, sync=False):
    return decorator


-def _run_single_rank(
+def wrapper_spawn_func(
    rank: int,
    world_size: int,
    backend: str,
@@ -108,108 +100,20 @@ def _run_single_rank(
    func: Callable,
    kwargs: dict,
 ):
-    with setup_parallel(
-        rank=rank,
-        world_size=world_size,
-        local_rank=rank,
-        backend=backend,
-        master_addr=master_addr,
-        master_port=master_port,
-        device_type=device_type,
-    ):
-        func(**kwargs)
-
-
-class LaunchStrategy(ABC):
-    """Strategy for launching a function in a distributed context."""
-
-    def __init__(
-        self,
-        world_size: int,
-        backend: str,
-        master_addr: str,
-        master_port: str,
-        device_type: str,
-        start_method: str,
-    ):
-        self.world_size = world_size
-        self.backend = backend
-        self.master_addr = master_addr
-        self.master_port = master_port
-        self.device_type = device_type
-        self.start_method = start_method
-
-    @abstractmethod
-    def launch(self, func: Callable, **kwargs):
-        raise NotImplementedError
-
-
-class TorchrunStrategy(LaunchStrategy):
-    """External orchestrator (torchrun, SLURM, K8s) — env vars pre-set."""
-
-    def launch(self, func: Callable, **kwargs):
-        rank = int(os.environ["RANK"])
-        world_size = int(os.environ["WORLD_SIZE"])
-        local_rank = int(os.environ.get("LOCAL_RANK", rank))
+    try:
        with setup_parallel(
            rank=rank,
            world_size=world_size,
-            local_rank=local_rank,
-            backend=self.backend,
-            master_addr=os.environ.get("MASTER_ADDR", self.master_addr),
-            master_port=os.environ.get("MASTER_PORT", self.master_port),
-            device_type=self.device_type,
+            backend=backend,
+            master_addr=master_addr,
+            master_port=master_port,
+            device_type=device_type,
        ):
            func(**kwargs)

-
-class LocalStrategy(LaunchStrategy):
-    """Local launcher — single-process or mp.start_processes."""
-
-    def launch(self, func: Callable, **kwargs):
-        args = (
-            self.world_size,
-            self.backend,
-            self.master_addr,
-            self.master_port,
-            self.device_type,
-            func,
-            kwargs,
-        )
-
-        if self.world_size == 1:
-            _run_single_rank(0, *args)
-            return
-
-        ctx = mp.start_processes(
-            _run_single_rank,
-            args=args,
-            nprocs=self.world_size,
-            start_method=self.start_method,
-            join=False,
-        )
-        try:
-            while not ctx.join():
-                pass
-        except BaseException:
-            for p in ctx.processes:
-                p.terminate()
-            ctx.join()
-            raise
-
-
-def _detect_launcher() -> str:
-    """Detect the distributed launcher from environment.
-
-    Returns one of: "torchelastic", "torchrun", "external", "local".
-    """
-    if dist.is_torchelastic_launched():
-        return "torchelastic"
-    if "LOCAL_WORLD_SIZE" in os.environ:
-        return "torchrun"
-    if "RANK" in os.environ and "WORLD_SIZE" in os.environ:
-        return "external"
-    return "local"
+    except Exception as e:
+        print(f"Error in rank {rank}: {e}")
+        raise


 def spawn_parallel_fn(
@@ -222,13 +126,42 @@ def spawn_parallel_fn(
    start_method: str = "spawn",
    **kwargs,
 ):
-    launcher = _detect_launcher()
-    if launcher in ("torchelastic", "torchrun", "external"):
-        strategy = TorchrunStrategy(
-            world_size, backend, master_addr, master_port, device_type, start_method
-        )
-    else:
-        strategy = LocalStrategy(
-            world_size, backend, master_addr, master_port, device_type, start_method
-        )
-    strategy.launch(func, **kwargs)
+    # clear environment variables
+    for key in [
+        "MASTER_ADDR",
+        "MASTER_PORT",
+        "RANK",
+        "WORLD_SIZE",
+        "LOCAL_RANK",
+        "LOCAL_DEVICE",
+    ]:
+        if key in os.environ:
+            del os.environ[key]
+
+    if world_size == 1:
+        device_id = torch.device(device_type, 0)
+        os.environ["LOCAL_RANK"] = "0"
+        os.environ["WORLD_SIZE"] = "1"
+        os.environ["LOCAL_DEVICE"] = str(device_id)
+
+        func(**kwargs)
+        return
+
+    wrapper_spawn_func_args = (
+        world_size,
+        backend,
+        master_addr,
+        master_port,
+        device_type,
+        func,
+        kwargs,
+    )
+
+    mp.start_processes(
+        wrapper_spawn_func,
+        args=wrapper_spawn_func_args,
+        nprocs=world_size,
+        start_method=start_method,
+        join=True,
+        daemon=True,
+    )
@@ -1,32 +0,0 @@
-from astrai.preprocessing.builder import (
-    BaseMaskBuilder,
-    MaskBuilderFactory,
-    SectionedMaskBuilder,
-)
-from astrai.preprocessing.packing import (
-    PackingStrategy,
-    PackingStrategyFactory,
-)
-from astrai.preprocessing.pipeline import Pipeline, filter_by_length
-from astrai.preprocessing.position_id import (
-    PositionIdStrategy,
-    PositionIdStrategyFactory,
-)
-from astrai.preprocessing.writer import (
-    StoreWriter,
-    StoreWriterFactory,
-)
-
-__all__ = [
-    "BaseMaskBuilder",
-    "MaskBuilderFactory",
-    "PackingStrategy",
-    "PackingStrategyFactory",
-    "Pipeline",
-    "PositionIdStrategy",
-    "PositionIdStrategyFactory",
-    "SectionedMaskBuilder",
-    "StoreWriter",
-    "StoreWriterFactory",
-    "filter_by_length",
-]
@@ -1,315 +0,0 @@
-"""Mask building for preprocessing pipeline.
-
-:class:`SectionRenderer` converts section specs into token ids and loss
-masks (template / text / value extraction).  :class:`SectionedMaskBuilder`
-orchestrates single-output / multi-output (DPO / GRPO) assembly.
-"""
-
-from abc import ABC, abstractmethod
-from typing import Optional
-
-from astrai.factory import BaseFactory
-
-
-def _extract_domain(item: dict, domain_key: Optional[str]) -> str:
-    if not domain_key:
-        return "__default__"
-    val = item.get(domain_key, "__default__")
-    return val if isinstance(val, str) else "__default__"
-
-
-def _resolve_action(action: str, role: str, config) -> str:
-    if action == "$role":
-        return config.mask.get(role, config.mask_default)
-    return action
-
-
-class SectionRenderer:
-    """Render section specs into ``(ids, loss_mask)`` tuples."""
-
-    def process_sections(
-        self,
-        item: dict,
-        sections: list,
-        config,
-        tokenizer,
-        *,
-        is_top_level: bool = False,
-    ):
-        all_ids: list[int] = []
-        loss_mask: list[int] = []
-
-        has_template = any(s.get("template") for s in sections)
-        is_text_config = not has_template and all(
-            s["action"] == "train" for s in sections
-        )
-
-        if is_top_level and has_template and tokenizer.bos_token_id is not None:
-            all_ids.append(tokenizer.bos_token_id)
-            loss_mask.append(0)
-
-        first_section = True
-        for sec in sections:
-            field = sec["field"]
-            action = sec["action"]
-            use_template = sec.get("template", False)
-            add_special = sec.get(
-                "add_special_tokens", not use_template and first_section
-            )
-
-            if use_template:
-                success = self._append_template(
-                    item, field, action, tokenizer, config, all_ids, loss_mask
-                )
-                if not success:
-                    continue
-            else:
-                success = self._append_text(
-                    item,
-                    field,
-                    action,
-                    tokenizer,
-                    add_special,
-                    is_text_config,
-                    config,
-                    all_ids,
-                    loss_mask,
-                )
-                if not success:
-                    continue
-
-            first_section = False
-
-        max_len = config.preprocessing.max_seq_len
-        all_ids = all_ids[:max_len]
-        loss_mask = loss_mask[: len(all_ids)]
-
-        if not all_ids:
-            return None, None
-
-        if is_top_level and has_template and len(all_ids) <= 1:
-            return None, None
-
-        return all_ids, loss_mask
-
-    def process_list_field(self, item: dict, sections: list, config, tokenizer):
-        all_ids: list[int] = []
-        loss_mask: list[int] = []
-
-        for sec in sections:
-            field = sec["field"]
-            action = sec["action"]
-            use_template = sec.get("template", False)
-
-            values = item.get(field)
-            if not isinstance(values, list):
-                continue
-
-            for val in values:
-                if use_template:
-                    if isinstance(val, list):
-                        wrapper = {field: val}
-                        self._append_template(
-                            wrapper,
-                            field,
-                            action,
-                            tokenizer,
-                            config,
-                            all_ids,
-                            loss_mask,
-                        )
-                else:
-                    wrapper = {field: str(val)}
-                    self._append_text(
-                        wrapper,
-                        field,
-                        action,
-                        tokenizer,
-                        False,
-                        False,
-                        config,
-                        all_ids,
-                        loss_mask,
-                    )
-
-        max_len = config.preprocessing.max_seq_len
-        all_ids = all_ids[:max_len]
-        loss_mask = loss_mask[: len(all_ids)]
-
-        if not all_ids:
-            return None, None
-        return all_ids, loss_mask
-
-    @staticmethod
-    def is_value_section(sections: list) -> bool:
-        return len(sections) == 1 and sections[0].get("action") == "value"
-
-    @staticmethod
-    def extract_raw_value(item: dict, sections: list):
-        sec = sections[0]
-        field = sec["field"]
-        raw = item.get(field)
-        if raw is None:
-            return None
-        if isinstance(raw, list):
-            return [float(v) for v in raw]
-        return [float(raw)]
-
-    def _append_template(
-        self, item, field, action, tokenizer, config, all_ids, loss_mask
-    ):
-        messages = item.get(field)
-        if not isinstance(messages, list) or not messages:
-            return False
-        for msg in messages:
-            role = msg.get("role", "")
-            act = _resolve_action(action, role, config)
-            rendered = tokenizer.apply_chat_template(
-                [msg], tokenize=False, add_generation_prompt=False
-            )
-            ids = tokenizer.encode(rendered, add_special_tokens=False)
-            all_ids.extend(ids)
-            val = 1 if act == "train" else 0
-            loss_mask.extend([val] * len(ids))
-        return True
-
-    def _append_text(
-        self,
-        item,
-        field,
-        action,
-        tokenizer,
-        add_special,
-        is_text_config,
-        config,
-        all_ids,
-        loss_mask,
-    ):
-        text = str(item.get(field, ""))
-        if not text.strip():
-            return False
-        if is_text_config:
-            pp = config.preprocessing
-            if pp.min_chars > 0 and len(text) < pp.min_chars:
-                return False
-            if len(text) > pp.max_chars:
-                return False
-        ids = tokenizer.encode(text, add_special_tokens=add_special)
-        all_ids.extend(ids)
-        val = 1 if action == "train" else 0
-        loss_mask.extend([val] * len(ids))
-        return True
-
-
-class BaseMaskBuilder(ABC):
-    """Convert a JSONL item into token ids and optional loss_mask."""
-
-    @abstractmethod
-    def build(self, item: dict, config, tokenizer) -> Optional[dict]: ...
-
-
-class MaskBuilderFactory(BaseFactory["BaseMaskBuilder"]):
-    pass
-
-
-@MaskBuilderFactory.register("sectioned")
-class SectionedMaskBuilder(BaseMaskBuilder):
-    """Config-driven builder supporting single and multi-output modes.
-
-    Single-output::
-
-        {"input": {"sections": [
-            {"field": "messages", "action": "$role", "template": true}
-        ]}}
-        → {"sequence": [...], "loss_mask": [...], "domain": "..."}
-
-    Multi-output (DPO / GRPO)::
-
-        {"input": {"sources": {
-            "chosen": {"sections": [{"field": "chosen", "action": "$role", "template": true}]},
-            "rejected": {"sections": [{"field": "rejected", "action": "$role", "template": true}]},
-        }}}
-        → {"chosen": [...], "chosen_mask": [...], "rejected": [...], "rejected_mask": [...], "domain": "..."}
-
-    Output spec fields::
-
-        sections      – list of section specs (same format as single-output)
-        list_field    – True when JSONL field holds a list (GRPO responses)
-        mask_key      – explicit loss-mask output key (default: ``"{output_key}_mask"``)
-    """
-
-    def __init__(self):
-        self.renderer = SectionRenderer()
-
-    def build(self, item: dict, config, tokenizer) -> Optional[dict]:
-        sources_spec = getattr(config.input, "sources", None)
-        if sources_spec:
-            return self._build_multi(item, sources_spec, config, tokenizer)
-        return self._build_single(item, config, tokenizer)
-
-    def _build_single(self, item: dict, config, tokenizer) -> Optional[dict]:
-        sections = config.input.sections
-        if not sections:
-            return None
-
-        ids, mask = self.renderer.process_sections(
-            item, sections, config, tokenizer, is_top_level=True
-        )
-        if ids is None:
-            return None
-
-        result: dict = {
-            "sequence": ids,
-            "domain": _extract_domain(item, config.output.domain_key),
-        }
-        if not all(m == 1 for m in mask):
-            result["loss_mask"] = mask
-        return result
-
-    def _build_multi(
-        self, item: dict, sources_spec: dict, config, tokenizer
-    ) -> Optional[dict]:
-        result: dict = {}
-        any_output = False
-
-        for output_key, spec in sources_spec.items():
-            sections = spec.get("sections", [])
-            if not sections:
-                continue
-
-            if self.renderer.is_value_section(sections):
-                ids = self.renderer.extract_raw_value(item, sections)
-                if ids is None:
-                    continue
-                result[output_key] = ids
-                any_output = True
-                continue
-
-            list_field = spec.get("list_field", False)
-            mask_key = spec.get("mask_key", f"{output_key}_mask")
-
-            if list_field:
-                ids, mask = self.renderer.process_list_field(
-                    item, sections, config, tokenizer
-                )
-            else:
-                ids, mask = self.renderer.process_sections(
-                    item, sections, config, tokenizer, is_top_level=True
-                )
-
-            if ids is None:
-                continue
-
-            result[output_key] = ids
-            if not all(m == 1 for m in mask):
-                result[mask_key] = mask
-            elif "mask_key" in spec:
-                result[mask_key] = mask
-
-            any_output = True
-
-        if not any_output:
-            return None
-
-        result["domain"] = _extract_domain(item, config.output.domain_key)
-        return result
@@ -1,121 +0,0 @@
-"""Sequence packing strategies for shard-level reordering and truncation.
-
-Each strategy receives the accumulated ``{key: [list of token lists]}``
-dict for a shard and returns a reordered / truncated version.  The
-pipeline later flattens the result into contiguous tensors.
-"""
-
-from abc import ABC, abstractmethod
-from typing import Dict, List
-
-from astrai.factory import BaseFactory
-
-
-def _truncate(seq: List[int], max_len: int, mode: str) -> List[int]:
-    if len(seq) <= max_len:
-        return seq
-    if mode == "keep_end":
-        return seq[-max_len:]
-    return seq[:max_len]
-
-
-class PackingStrategy(ABC):
-    """Reorder and truncate sequences within a shard."""
-
-    @abstractmethod
-    def apply(
-        self,
-        keys: Dict[str, List[List[int]]],
-        max_packed_len: int,
-        truncation_mode: str,
-    ) -> Dict[str, List[List[int]]]:
-        raise NotImplementedError
-
-
-class PackingStrategyFactory(BaseFactory["PackingStrategy"]):
-    pass
-
-
-@PackingStrategyFactory.register("simple")
-class SimplePacking(PackingStrategy):
-    def apply(
-        self,
-        keys: Dict[str, List[List[int]]],
-        max_packed_len: int,
-        truncation_mode: str,
-    ) -> Dict[str, List[List[int]]]:
-        return {
-            k: [_truncate(v, max_packed_len, truncation_mode) for v in vals]
-            for k, vals in keys.items()
-        }
-
-
-@PackingStrategyFactory.register("bfd")
-class BFDPacking(PackingStrategy):
-    """Best-Fit Decreasing bin packing.
-
-    Assigns sequences to bins using a best-fit heuristic (sorted by
-    decreasing length) and concatenates sequences within each bin into
-    a single packed sequence.  Packed sequences are truncated to
-    *max_packed_len* so that each packed bin fits within one context
-    window during training.
-    """
-
-    def apply(
-        self,
-        keys: Dict[str, List[List[int]]],
-        max_packed_len: int,
-        truncation_mode: str,
-    ) -> Dict[str, List[List[int]]]:
-        sequences = keys.get("sequence", [])
-        if not sequences:
-            return keys
-        bins = self._plan(sequences, max_packed_len, truncation_mode)
-
-        packed: Dict[str, List[List[int]]] = {}
-        for k, vals in keys.items():
-            packed[k] = [
-                _truncate(
-                    self._concat_bin(vals, bin_indices),
-                    max_packed_len,
-                    truncation_mode,
-                )
-                for bin_indices in bins
-            ]
-        return packed
-
-    @staticmethod
-    def _concat_bin(vals: List[List[int]], indices: List[int]) -> List[int]:
-        result: List[int] = []
-        for i in indices:
-            result.extend(vals[i])
-        return result
-
-    @staticmethod
-    def _plan(
-        sequences: List[List[int]], max_packed_len: int, truncation_mode: str
-    ) -> List[List[int]]:
-        n = len(sequences)
-        order = sorted(range(n), key=lambda i: len(sequences[i]), reverse=True)
-        bins: List[List[int]] = []
-        bin_lengths: List[int] = []
-
-        for orig_idx in order:
-            seq_len = len(
-                _truncate(sequences[orig_idx], max_packed_len, truncation_mode)
-            )
-            best_bin = None
-            best_remain = max_packed_len + 1
-            for i, bl in enumerate(bin_lengths):
-                remain = max_packed_len - bl
-                if seq_len <= remain < best_remain:
-                    best_remain = remain
-                    best_bin = i
-            if best_bin is not None:
-                bins[best_bin].append(orig_idx)
-                bin_lengths[best_bin] += seq_len
-            else:
-                bins.append([orig_idx])
-                bin_lengths.append(seq_len)
-
-        return bins
@@ -1,192 +0,0 @@
-"""Config-driven JSONL preprocessing pipeline.
-
-Composes a :class:`BaseMaskBuilder` (selected by ``input.type``) with
-sharding and flush to ``.h5`` / ``.bin`` storage.  Packing, position-id
-generation and storage writing are each delegated to pluggable strategies,
-dispatched by configuration keys.
-"""
-
-import json
-import logging
-import os
-from collections import defaultdict
-from itertools import chain
-from typing import Dict, List, Optional
-
-import torch
-import tqdm
-
-from astrai.config.preprocess_config import PipelineConfig
-from astrai.preprocessing.builder import MaskBuilderFactory
-from astrai.preprocessing.packing import PackingStrategyFactory
-from astrai.preprocessing.position_id import PositionIdStrategyFactory
-from astrai.preprocessing.writer import StoreWriterFactory
-from astrai.tokenize import AutoTokenizer
-
-logger = logging.getLogger(__name__)
-
-_STR_TO_DTYPE: dict[str, torch.dtype] = {
-    "bool": torch.bool,
-    "uint8": torch.uint8,
-    "int8": torch.int8,
-    "int16": torch.int16,
-    "int32": torch.int32,
-    "int64": torch.int64,
-    "float16": torch.float16,
-    "float32": torch.float32,
-    "float64": torch.float64,
-}
-
-
-def filter_by_length(text: str, min_len: int = 50, max_len: int = 2_000_000) -> bool:
-    return min_len <= len(text) <= max_len
-
-
-class Pipeline:
-    """Tokenization pipeline driven by a declarative :class:`PipelineConfig`.
-
-    Usage::
-
-        config = PipelineConfig.from_file("sft_pipeline.json")
-        Pipeline(config, ["data.jsonl"], output_dir="out", tokenizer_path="params").run()
-    """
-
-    def __init__(
-        self,
-        config: PipelineConfig,
-        input_paths: list[str],
-        output_dir: str,
-        tokenizer_path: str,
-    ):
-        os.makedirs(output_dir, exist_ok=True)
-        self.config = config
-        self.paths = input_paths
-        self.output_dir = output_dir
-        self.tokenizer_path = tokenizer_path
-
-        self.mask_builder = MaskBuilderFactory.create("sectioned")
-        self._packer = PackingStrategyFactory.create(
-            config.preprocessing.packing_strategy
-        )
-        self._position_id = PositionIdStrategyFactory.create(
-            config.output.position_ids_mode
-        )
-        self._writer = StoreWriterFactory.create(config.output.storage_format)
-
-    def transform(self, item: dict) -> Optional[dict]:
-        return self.mask_builder.build(item, self.config, self._tokenizer)
-
-    def run(self):
-        self._tokenizer = AutoTokenizer.from_pretrained(self.tokenizer_path)
-        domains: dict = defaultdict(lambda: defaultdict(list))
-        total_tokens = 0
-        shard_idx: dict[str, int] = defaultdict(int)
-        count = 0
-
-        pp = self.config.preprocessing
-
-        for item in tqdm.tqdm(
-            self._iter_items(), desc="Tokenizing", unit="docs", mininterval=0.5
-        ):
-            if pp.max_items and count >= pp.max_items:
-                break
-
-            try:
-                result = self.transform(item)
-            except Exception:
-                logger.warning(
-                    "Failed to process item #%d, skipping", count + 1, exc_info=True
-                )
-                continue
-            if result is None:
-                continue
-
-            domain = result.pop("domain", "__default__")
-
-            is_multi = bool(getattr(self.config.input, "sources", None))
-            if is_multi:
-                ids = self._primary_ids(result)
-            else:
-                ids = result.pop("sequence")
-                result["sequence"] = ids
-
-            if not ids:
-                continue
-
-            bucket = domains[domain]
-            self._align_bucket(bucket, result, ids)
-            for key, val in result.items():
-                bucket[key].append(val)
-
-            count += 1
-            total_tokens += len(ids)
-
-            if total_tokens >= self.config.output.max_tokens_per_shard:
-                self._flush(domains, shard_idx)
-                domains.clear()
-                total_tokens = 0
-
-        if total_tokens > 0:
-            self._flush(domains, shard_idx)
-
-    @staticmethod
-    def _primary_ids(result: dict) -> list:
-        """Return the first list-valued entry in *result* as the primary id
-        sequence for token counting."""
-        for val in result.values():
-            if isinstance(val, list) and val and isinstance(val[0], int):
-                return val
-        return []
-
-    @staticmethod
-    def _align_bucket(bucket: dict, result: dict, ids: list):
-        """Pad previously-accumulated keys that are missing from *result*."""
-        for key in list(bucket.keys()):
-            if key in result:
-                continue
-            bucket[key].append([0] * len(ids))
-
-    def _iter_items(self):
-        for path in self.paths:
-            with open(path, "r", encoding="utf-8") as f:
-                for line in f:
-                    line = line.strip()
-                    if not line:
-                        continue
-                    yield json.loads(line)
-
-    def _flush(self, domains, shard_idx):
-        for domain, keys in domains.items():
-            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]] = {}
-            for key, ids_list in keys.items():
-                dt = _STR_TO_DTYPE.get(
-                    self.config.output.dtype.get(key, "int32"), torch.int32
-                )
-                tensors[key] = [
-                    torch.tensor(list(chain.from_iterable(ids_list)), dtype=dt)
-                ]
-
-            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
-
-            first_key = "sequence" if "sequence" in tensors else next(iter(tensors))
-            tqdm.tqdm.write(
-                f"  saved {domain}/shard_{idx:04d}  "
-                f"({tensors[first_key][0].numel():,} tokens)"
-            )
@@ -1,46 +0,0 @@
-"""Position-id generation strategies for packed sequences.
-
-Each strategy takes the list of per-document token sequences after packing
-and returns a flat list of position ids (same total length as all
-sequences combined).  The pipeline wraps the result into a tensor and
-attaches it as ``position_ids``.
-"""
-
-from abc import ABC, abstractmethod
-from typing import List
-
-from astrai.factory import BaseFactory
-
-
-class PositionIdStrategy(ABC):
-    """Generate ``position_ids`` for packed sequences."""
-
-    @abstractmethod
-    def generate(self, sequences: List[List[int]]) -> List[int]:
-        raise NotImplementedError
-
-
-class PositionIdStrategyFactory(BaseFactory["PositionIdStrategy"]):
-    pass
-
-
-@PositionIdStrategyFactory.register("none")
-class NoPositionId(PositionIdStrategy):
-    def generate(self, sequences: List[List[int]]) -> List[int]:
-        return []
-
-
-@PositionIdStrategyFactory.register("doc_reset")
-class DocResetPositionId(PositionIdStrategy):
-    def generate(self, sequences: List[List[int]]) -> List[int]:
-        pos_ids = []
-        for seq in sequences:
-            pos_ids.extend(range(len(seq)))
-        return pos_ids
-
-
-@PositionIdStrategyFactory.register("continuous")
-class ContinuousPositionId(PositionIdStrategy):
-    def generate(self, sequences: List[List[int]]) -> List[int]:
-        total = sum(len(seq) for seq in sequences)
-        return list(range(total))
@@ -1,75 +0,0 @@
-"""Storage writer strategies for pipeline output.
-
-The :class:`StoreWriter` abstraction decouples the pipeline from the
-concrete storage format (bin / h5).  The pipeline builds a ``{key:
-List[Tensor]}`` dict and delegates the write to the writer selected
-by ``output.storage_format``.
-"""
-
-import logging
-import os
-import shutil
-from abc import ABC, abstractmethod
-from typing import Dict, List
-
-import torch
-
-from astrai.factory import BaseFactory
-from astrai.serialization import save_bin, save_h5
-
-logger = logging.getLogger(__name__)
-
-
-class StoreWriter(ABC):
-    """Write pre-tokenized tensors to disk in a format-specific way."""
-
-    @abstractmethod
-    def save(
-        self,
-        output_dir: str,
-        domain: str,
-        shard_idx: int,
-        tensors: Dict[str, List[torch.Tensor]],
-    ) -> None: ...
-
-
-class StoreWriterFactory(BaseFactory["StoreWriter"]):
-    pass
-
-
-@StoreWriterFactory.register("bin")
-class BinWriter(StoreWriter):
-    def save(self, output_dir, domain, shard_idx, tensors):
-        shard_path = os.path.join(output_dir, domain, f"shard_{shard_idx:04d}")
-        try:
-            save_bin(shard_path, tensors)
-        except Exception:
-            if os.path.exists(shard_path):
-                shutil.rmtree(shard_path, ignore_errors=True)
-            logger.error(
-                "Failed to write shard %s/%s_%04d, cleaned up partial output",
-                domain,
-                "shard",
-                shard_idx,
-                exc_info=True,
-            )
-            raise
-
-
-@StoreWriterFactory.register("h5")
-class H5Writer(StoreWriter):
-    def save(self, output_dir, domain, shard_idx, tensors):
-        chunk_dir = os.path.join(output_dir, domain)
-        file_path = os.path.join(chunk_dir, f"data_{shard_idx:04d}.h5")
-        try:
-            save_h5(chunk_dir, f"data_{shard_idx:04d}", tensors)
-        except Exception:
-            if os.path.exists(file_path):
-                os.remove(file_path)
-            logger.error(
-                "Failed to write shard %s/data_%04d.h5, cleaned up partial output",
-                domain,
-                shard_idx,
-                exc_info=True,
-            )
-            raise
@@ -1,21 +0,0 @@
-"""Training component protocols — structural subtyping for optimizer/scheduler wrappers."""
-
-from typing import Any, Protocol, runtime_checkable
-
-
-@runtime_checkable
-class OptimizerProtocol(Protocol):
-    def step(self, closure=None): ...
-    def zero_grad(self): ...
-    @property
-    def param_groups(self) -> Any: ...
-    def state_dict(self) -> dict: ...
-    def load_state_dict(self, d: dict): ...
-
-
-@runtime_checkable
-class SchedulerProtocol(Protocol):
-    def step(self): ...
-    def state_dict(self) -> dict: ...
-    def load_state_dict(self, d: dict): ...
-    def get_last_lr(self): ...
@@ -0,0 +1,83 @@
+import json
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import safetensors.torch as st
+import torch
+import torch.distributed as dist
+
+from astrai.parallel.setup import get_rank
+
+
+class Checkpoint:
+    def __init__(
+        self,
+        state_dict: Dict[str, Any],
+        epoch: int = 0,
+        iteration: int = 0,
+        extra: Optional[Dict[str, Any]] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ):
+        self.state_dict = state_dict
+        self.epoch = epoch
+        self.iteration = iteration
+        self.extra = extra or {}
+        self.meta = meta or {}
+
+    def save(
+        self,
+        save_dir: str,
+    ) -> None:
+
+        save_path = Path(save_dir)
+        save_path.mkdir(parents=True, exist_ok=True)
+
+        rank = get_rank()
+        if rank == 0:
+            meta = {
+                "epoch": self.epoch,
+                "iteration": self.iteration,
+                "timestamp": time.time(),
+            }
+            meta.update(self.meta)
+            with open(save_path / "meta.json", "w") as f:
+                json.dump(meta, f, indent=2)
+
+            st.save_file(self.state_dict, save_path / "state_dict.safetensors")
+            if self.extra:
+                for key, value in self.extra.items():
+                    torch.save(value, save_path / f"{key}.pt")
+
+    @classmethod
+    def load(
+        cls,
+        save_dir: str,
+    ) -> "Checkpoint":
+
+        rank = get_rank()
+        save_path = Path(save_dir)
+
+        meta = {}
+        if rank == 0:
+            with open(Path(save_dir) / "meta.json", "r") as f:
+                meta = json.load(f)
+
+        if dist.is_initialized():
+            meta_list = [meta]
+            dist.broadcast_object_list(meta_list, src=0)
+            meta = meta_list[0]
+
+        state_dict = st.load_file(save_path / "state_dict.safetensors")
+
+        extra = {}
+        for f in save_path.iterdir():
+            if f.suffix == ".pt" and f.stem not in ("meta",):
+                extra[f.stem] = torch.load(f, map_location="cpu", weights_only=False)
+
+        return cls(
+            state_dict=state_dict,
+            epoch=meta["epoch"],
+            iteration=meta["iteration"],
+            extra=extra or None,
+        )
@@ -1,43 +0,0 @@
-"""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,204 +0,0 @@
-"""Model checkpoint serialization helpers."""
-
-import io
-import json
-import os
-import time
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Dict, Optional, Union
-
-import safetensors.torch as st
-import torch
-import torch.distributed as dist
-
-from astrai.parallel.setup import get_rank
-
-_META_FILE = "meta.json"
-_CONFIG_FILE = "config.json"
-_WEIGHTS_FILE = "model.safetensors"
-
-
-def save_safetensors(state_dict: dict, path: Union[str, Path]):
-    st.save_file(state_dict, str(path))
-
-
-def load_safetensors(path: Union[str, Path], broadcast: bool = False) -> dict:
-    if not broadcast or not dist.is_initialized():
-        return st.load_file(str(path))
-
-    rank = get_rank()
-    if rank == 0:
-        state_dict = st.load_file(str(path))
-    else:
-        state_dict = {}
-    tmp = [state_dict]
-    dist.broadcast_object_list(tmp, src=0)
-    return tmp[0]
-
-
-def save_json(data: dict, path: Union[str, Path]):
-    with open(str(path), "w") as f:
-        json.dump(data, f, indent=2)
-
-
-def load_json(path: Union[str, Path], broadcast: bool = False) -> dict:
-    if not broadcast or not dist.is_initialized():
-        with open(str(path), "r") as f:
-            return json.load(f)
-
-    rank = get_rank()
-    if rank == 0:
-        with open(str(path), "r") as f:
-            data = json.load(f)
-    else:
-        data = {}
-    tmp = [data]
-    dist.broadcast_object_list(tmp, src=0)
-    return tmp[0]
-
-
-def save_torch(obj: Any, path: Union[str, Path]):
-    torch.save(obj, str(path))
-
-
-def load_torch(path: Union[str, Path], broadcast: bool = False) -> Any:
-    if not broadcast or not dist.is_initialized():
-        return torch.load(str(path), map_location="cpu", weights_only=False)
-
-    path = Path(path)
-    rank = get_rank()
-
-    if rank == 0:
-        with open(path, "rb") as f:
-            raw = f.read()
-        data_tensor = torch.frombuffer(bytearray(raw), dtype=torch.uint8)
-        num_bytes = torch.tensor([len(raw)], dtype=torch.long)
-    else:
-        num_bytes = torch.tensor([0], dtype=torch.long)
-
-    dist.broadcast(num_bytes, src=0)
-
-    if rank != 0:
-        data_tensor = torch.empty(num_bytes.item(), dtype=torch.uint8)
-
-    dist.broadcast(data_tensor, src=0)
-
-    buf = io.BytesIO(data_tensor.numpy().tobytes())
-    return torch.load(buf, map_location="cpu", weights_only=False)
-
-
-def save_model(config: dict, state_dict: dict, save_directory: str):
-    save_path = Path(save_directory)
-    save_path.mkdir(parents=True, exist_ok=True)
-    save_json(config, save_path / _CONFIG_FILE)
-    save_safetensors(state_dict, save_path / _WEIGHTS_FILE)
-
-
-def load_model_config(save_directory: str) -> dict:
-    return load_json(Path(save_directory) / _CONFIG_FILE)
-
-
-def load_model_weights(save_directory: str) -> dict:
-    return load_state_dict(Path(save_directory) / _WEIGHTS_FILE)
-
-
-def load_state_dict(path: Union[str, Path], broadcast: bool = False) -> dict:
-    path = Path(path)
-    if not broadcast or not dist.is_initialized():
-        return load_safetensors(path)
-
-    rank = get_rank()
-    if rank == 0:
-        state_dict = load_safetensors(path)
-        specs = [
-            (k, list(state_dict[k].shape), str(state_dict[k].dtype).split(".")[-1])
-            for k in sorted(state_dict)
-        ]
-    else:
-        state_dict = {}
-        specs = []
-
-    specs_list = [specs]
-    dist.broadcast_object_list(specs_list, src=0)
-    specs = specs_list[0]
-
-    for key, shape, dtype_name in specs:
-        dtype = getattr(torch, dtype_name)
-        if rank != 0:
-            tensor = torch.empty(shape, dtype=dtype, device="cpu")
-        else:
-            tensor = state_dict[key].contiguous().cpu()
-        dist.broadcast(tensor, src=0)
-        if rank != 0:
-            state_dict[key] = tensor
-    return state_dict
-
-
-@dataclass
-class Checkpoint:
-    state_dict: Dict[str, Any] = field(default_factory=dict)
-    epoch: 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)
-
-    def save(self, save_dir: str):
-        save_path = Path(save_dir)
-        save_path.mkdir(parents=True, exist_ok=True)
-
-        if get_rank() != 0:
-            return
-
-        meta = {
-            "epoch": self.epoch,
-            "consumed_samples": self.consumed_samples,
-            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
-            **self.meta,
-        }
-        save_json(meta, save_path / _META_FILE)
-        save_json(self.config, save_path / _CONFIG_FILE)
-        save_safetensors(self.state_dict, save_path / _WEIGHTS_FILE)
-        for key, value in self.extra.items():
-            save_torch(value, save_path / f"{key}.pt")
-
-    @classmethod
-    def load(cls, save_dir: str, broadcast: bool = False) -> "Checkpoint":
-        save_path = Path(save_dir)
-
-        meta = load_json(save_path / _META_FILE, broadcast)
-        config = load_json(save_path / _CONFIG_FILE, broadcast)
-        state_dict = load_state_dict(save_path / _WEIGHTS_FILE, broadcast=broadcast)
-
-        extra = {}
-        for f in sorted(save_path.iterdir()):
-            if f.suffix == ".pt":
-                extra[f.stem] = load_torch(f, broadcast=broadcast)
-
-        return cls(
-            state_dict=state_dict,
-            epoch=meta.get("epoch", 0),
-            consumed_samples=meta.get("consumed_samples", 0),
-            extra=extra,
-            config=config,
-        )
-
-    @classmethod
-    def load_any(cls, save_dir: str, broadcast: bool = False) -> Optional["Checkpoint"]:
-        save_path = Path(save_dir)
-        meta_path = save_path / _META_FILE
-        weights_path = save_path / _WEIGHTS_FILE
-
-        if meta_path.exists():
-            return cls.load(save_dir, broadcast=broadcast)
-
-        if weights_path.exists():
-            state_dict = load_state_dict(weights_path, broadcast=broadcast)
-            config = {}
-            config_path = save_path / _CONFIG_FILE
-            if config_path.exists():
-                config = load_json(config_path, broadcast)
-            return cls(state_dict=state_dict, config=config)
-
-        return None
@@ -1,73 +0,0 @@
-"""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,10 +1,13 @@
+from dataclasses import dataclass
 from typing import Any, Dict, List, Optional

 from jinja2 import Template

+# Message type for chat messages
 type MessageType = Dict[str, Any]


+@dataclass
 class ChatTemplate:
    """A chat template with Jinja2 rendering support.

@@ -12,24 +15,23 @@ class ChatTemplate:
        name: Unique identifier for the template.
        template_str: Jinja2 template string.
        description: Optional description.
-        default_variables: Optional dictionary of default variable values.
+        default_variables: Optional dictionary of default variable values
+            that will be passed to the template if not overridden during rendering.
        special_tokens: Optional dictionary mapping token names to their string values.
+            These tokens are automatically added to the template variables.
    """

-    def __init__(
-        self,
-        name: str = "",
-        template_str: str = "",
-        description: str = "",
-        default_variables: Optional[Dict[str, Any]] = None,
-        special_tokens: Optional[Dict[str, str]] = None,
-    ):
-        self.name = name
-        self.template_str = template_str
-        self.description = description
-        self.default_variables = default_variables or {}
-        self.special_tokens = special_tokens or {}
-        self._compiled: Template = Template(template_str)
+    name: str
+    template_str: str
+    description: str = ""
+    default_variables: Dict[str, Any] = None
+    special_tokens: Dict[str, str] = None
+
+    def __post_init__(self):
+        if self.default_variables is None:
+            self.default_variables = {}
+        if self.special_tokens is None:
+            self.special_tokens = {}

    @classmethod
    def from_string(
@@ -41,7 +43,7 @@ class ChatTemplate:
    ) -> "ChatTemplate":
        """Create a ChatTemplate instance directly from a template string."""
        return cls(
-            name="",
+            name="",  # empty name for ad‑hoc templates
            template_str=template_str,
            description=description,
            default_variables=default_variables,
@@ -71,4 +73,5 @@ class ChatTemplate:
        if system_prompt is not None:
            variables["system_prompt"] = system_prompt

-        return self._compiled.render(**variables)
+        jinja_template = Template(self.template_str)
+        return jinja_template.render(**variables)
@@ -1,3 +1,4 @@
+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 (
@@ -9,6 +10,8 @@ from astrai.trainer.trainer import Trainer
 __all__ = [
    # Main trainer
    "Trainer",
+    # Optimizer
+    "Muon",
    # Strategy factory
    "StrategyFactory",
    "BaseStrategy",
@@ -1,25 +1,42 @@
-from typing import Dict
+from typing import Any, Callable, Dict

 import torch
 import torch.nn as nn


-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_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

-    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 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)


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


 def ctx_get_grad_norm(ctx):
-    return ctx.grad_norm
+    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)
@@ -0,0 +1,113 @@
+import torch
+from torch.optim import Optimizer
+
+
+def _zeropower_via_newtonschulz(G: torch.Tensor, steps: int = 5):
+    assert G.ndim == 2
+    X = G.bfloat16()
+    scale = max(1, G.size(0) / G.size(1)) ** 0.5
+    X = X / (X.norm() + 1e-7) * scale
+    if steps == 0:
+        return X.type_as(G)
+    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.type_as(G)
+
+
+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:
+            for p in group["params"]:
+                if p.grad is None:
+                    continue
+                grad = p.grad
+                if grad.is_sparse:
+                    raise RuntimeError("Muon does not support sparse gradients")
+                if p.ndim >= 2:
+                    self._muon_update(p, grad, group)
+                else:
+                    self._adamw_update(p, grad, group)
+        return loss
+
+    def _muon_update(self, p, grad, group):
+        lr = group["lr"]
+        momentum = group["momentum"]
+        wd = group["weight_decay"]
+        nesterov = group["nesterov"]
+        ns_steps = group["ns_steps"]
+        state = self.state[p]
+
+        p.mul_(1 - lr * wd)
+
+        if nesterov:
+            grad = grad.add(p, alpha=wd)
+
+        if "momentum_buffer" not in state:
+            state["momentum_buffer"] = torch.zeros_like(grad)
+        buf = state["momentum_buffer"]
+        buf.lerp_(grad, 1 - momentum)
+
+        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(self, p, grad, group):
+        lr = group["adamw_lr"]
+        betas = group["adamw_betas"]
+        eps = group["adamw_eps"]
+        wd = group["adamw_wd"]
+        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)
+
+        state["step"] += 1
+        exp_avg, exp_avg_sq = state["exp_avg"], state["exp_avg_sq"]
+        beta1, beta2 = betas
+
+        exp_avg.lerp_(grad, 1 - beta1)
+        exp_avg_sq.lerp_(grad.square(), 1 - beta2)
+
+        step = state["step"]
+        bias1 = 1 - beta1**step
+        bias2 = 1 - beta2**step
+
+        p.mul_(1 - lr * wd)
+        denom = exp_avg_sq.sqrt().div_(bias2**0.5).add_(eps)
+        p.addcdiv_(exp_avg / bias1, denom, value=-lr)
@@ -2,7 +2,7 @@

 import math
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Type

 from torch.optim.lr_scheduler import LRScheduler

@@ -31,6 +31,7 @@ class SchedulerFactory(BaseFactory["BaseScheduler"]):
    """Factory class for creating learning rate schedulers.

    Supports decorator-based registration for extensible scheduler types.
+    Also supports creation from ScheduleConfig objects.

    Example usage:
        @SchedulerFactory.register("custom")
@@ -40,6 +41,33 @@ class SchedulerFactory(BaseFactory["BaseScheduler"]):
        scheduler = SchedulerFactory.create("custom", optimizer, **kwargs)
    """

+    @classmethod
+    def _validate_component(cls, scheduler_cls: Type[BaseScheduler]) -> None:
+        """Validate that the scheduler class inherits from BaseScheduler."""
+        if not issubclass(scheduler_cls, BaseScheduler):
+            raise TypeError(f"{scheduler_cls.__name__} must inherit from BaseScheduler")
+
+    @classmethod
+    def create(
+        cls, optimizer, schedule_type: str = "none", **kwargs
+    ) -> "BaseScheduler":
+        """Create a scheduler instance by type name.
+
+        Args:
+            optimizer: PyTorch optimizer
+            schedule_type: Type of scheduler ("cosine", "sgdr")
+            **kwargs: Arguments passed to the scheduler constructor
+
+        Returns:
+            Scheduler instance
+        """
+        return super().create(schedule_type, optimizer, **kwargs)
+
+    @classmethod
+    def available_types(cls) -> list:
+        """Return list of registered scheduler type names."""
+        return cls.list_registered()
+

 # ----------- Scheduler implementations -----------

@@ -53,7 +81,7 @@ class CosineScheduler(BaseScheduler):
        optimizer,
        warmup_steps: int,
        lr_decay_steps: int,
-        min_rate: float = 0.01,
+        min_rate: float = 0.05,
        last_epoch: int = -1,
    ):
        self.warmup_steps = warmup_steps
@@ -65,15 +93,11 @@ 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 / max(self.warmup_steps, 1)
-            )
+            warmup_factor = max(self.min_rate, self.last_epoch / self.warmup_steps)
            return [base_lr * warmup_factor for base_lr in self.base_lrs]

        # cosine decay
-        decay_progress = (self.last_epoch - self.warmup_steps) / max(
-            self.lr_decay_steps, 1
-        )
+        decay_progress = (self.last_epoch - self.warmup_steps) / self.lr_decay_steps
        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)
@@ -108,7 +132,7 @@ class SGDRScheduler(BaseScheduler):
        optimizer,
        warmup_steps: int,
        cycle_length: int,
-        min_rate: float = 0.01,
+        min_rate: float = 0.05,
        t_mult: int = 2,
        last_epoch: int = -1,
    ):
@@ -122,9 +146,7 @@ class SGDRScheduler(BaseScheduler):
    def get_lr(self):
        # warmup
        if self.last_epoch < self.warmup_steps:
-            warmup_factor = max(
-                self.min_rate, self.last_epoch / max(self.warmup_steps, 1)
-            )
+            warmup_factor = max(self.min_rate, self.last_epoch / self.warmup_steps)
            return [base_lr * warmup_factor for base_lr in self.base_lrs]

        # SGDR
@@ -170,66 +192,3 @@ class SGDRScheduler(BaseScheduler):
        self.min_rate = state_dict.pop("min_rate")
        self.t_mult = state_dict.pop("t_mult")
        super().load_state_dict(state_dict)
-
-
-@SchedulerFactory.register("wsd")
-class WSDScheduler(BaseScheduler):
-    """WSD (Warmup-Stable-Decay) scheduler with sqrt cooldown.
-
-    warmup_steps:  linear warmup from min_rate to 1.0
-    stable_steps:   constant at base_lr
-    decay_steps:    sqrt decay from base_lr to min_rate
-    min_rate:       minimum lr as fraction of base_lr (default 0.0)
-    """
-
-    def __init__(
-        self,
-        optimizer,
-        warmup_steps: int,
-        stable_steps: int,
-        decay_steps: int,
-        min_rate: float = 0.01,
-        last_epoch: int = -1,
-    ):
-        self.warmup_steps = warmup_steps
-        self.stable_steps = stable_steps
-        self.decay_steps = decay_steps
-        self.min_rate = min_rate
-        self.total_steps = warmup_steps + stable_steps + decay_steps
-        super().__init__(optimizer, last_epoch)
-
-    def get_lr(self) -> List[float]:
-        if self.last_epoch < self.warmup_steps:
-            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
-
-        if offset < self.stable_steps:
-            return list(self.base_lrs)
-
-        decay_ratio = (offset - self.stable_steps) / max(self.decay_steps, 1)
-        decay_ratio = min(decay_ratio, 1.0)
-        factor = (1.0 - self.min_rate) * (1.0 - decay_ratio) ** 2 + self.min_rate
-        return [base_lr * factor for base_lr in self.base_lrs]
-
-    def state_dict(self):
-        state = super().state_dict()
-        state.update(
-            {
-                "warmup_steps": self.warmup_steps,
-                "stable_steps": self.stable_steps,
-                "decay_steps": self.decay_steps,
-                "min_rate": self.min_rate,
-                "total_steps": self.total_steps,
-            }
-        )
-        return state
-
-    def load_state_dict(self, state_dict):
-        self.warmup_steps = state_dict.pop("warmup_steps")
-        self.stable_steps = state_dict.pop("stable_steps")
-        self.decay_steps = state_dict.pop("decay_steps")
-        self.min_rate = state_dict.pop("min_rate")
-        self.total_steps = state_dict.pop("total_steps")
-        super().load_state_dict(state_dict)
@@ -1,28 +1,39 @@
 """Training strategy implementations with factory pattern."""

+import copy
 from abc import ABC, abstractmethod
-from typing import Callable, Dict, Union
+from typing import Any, Callable, Dict, Union

 import torch
 import torch.nn as nn
 import torch.nn.functional as F
 from torch import Tensor
+from torch.nn.parallel import DistributedDataParallel as DDP

 from astrai.factory import BaseFactory


-def create_ref_model(
-    model_fn: Callable[[], nn.Module], state_dict: Dict[str, Tensor]
-) -> nn.Module:
-    """Create a frozen reference model from model_fn + full state dict."""
-    ref_model = model_fn()
-    ref_model.load_state_dict(state_dict)
+def unwrap_model(model: nn.Module) -> nn.Module:
+    """Unwrap DDP wrapper if present to get the original model."""
+    if isinstance(model, DDP):
+        return model.module
+    return model
+
+
+def create_ref_model(model: nn.Module) -> nn.Module:
+    """Create a reference model for DPO/GRPO training.
+
+    Handles DDP-wrapped models safely by unwrapping first,
+    then creating a deep copy with frozen gradients.
+    """
+    original_model = unwrap_model(model)
+    ref_model = copy.deepcopy(original_model)
    ref_model.requires_grad_(False)
    ref_model.eval()
    return ref_model


-def move_to_device(batch: Dict[str, Tensor], device: str) -> Dict[str, Tensor]:
+def move_to_device(batch: Dict[str, Tensor], device: str) -> Any:
    """Move batch tensors to specified device with non-blocking transfer."""
    return {key: value.to(device, non_blocking=True) for key, value in batch.items()}

@@ -32,7 +43,7 @@ def get_logprobs(
    input_ids: Tensor,
    mask: Tensor,
    reduction: str,
-) -> Tensor:
+):
    """Compute token-wise log probabilities from model outputs.

    Args:
@@ -70,35 +81,14 @@ def get_logprobs(
        return token_logprobs * shifted_mask


-def make_doc_boundary_mask(position_ids: Tensor) -> Tensor:
-    S = position_ids.size(1)
-    device = position_ids.device
-    boundaries = position_ids[:, 1:] <= position_ids[:, :-1]
-    doc_ids = torch.cat(
-        [
-            torch.zeros(position_ids.size(0), 1, dtype=torch.long, device=device),
-            boundaries.long().cumsum(dim=1),
-        ],
-        dim=1,
-    )
-    same_doc = doc_ids.unsqueeze(-1) == doc_ids.unsqueeze(-2)
-    causal = torch.tril(torch.ones(S, S, dtype=torch.bool, device=device))
-    return (same_doc & causal).unsqueeze(1)
-
-
 class BaseStrategy(ABC):
    """Abstract base class for training strategies."""

    def __init__(
-        self,
-        model: Union[nn.Module, Callable[..., Dict[str, Tensor]]],
-        device: str,
-        **kwargs,
+        self, model: Union[Callable[..., Dict[str, Tensor]]], device: str, **kwargs
    ):
        self.model = model
        self.device = device
-        self.executor = kwargs.pop("executor", None)
-        self.model_fn = kwargs.pop("model_fn", None)
        self.extra_kwargs = kwargs

    @abstractmethod
@@ -132,6 +122,32 @@ class StrategyFactory(BaseFactory["BaseStrategy"]):
        strategy = StrategyFactory.create("custom", model, device)
    """

+    @classmethod
+    def _validate_component(cls, strategy_cls: type) -> None:
+        """Validate that the strategy class inherits from BaseStrategy."""
+        if not issubclass(strategy_cls, BaseStrategy):
+            raise TypeError(f"{strategy_cls.__name__} must inherit from BaseStrategy")
+
+    @classmethod
+    def create(cls, train_type: str, model, device: str, **kwargs) -> "BaseStrategy":
+        """Create a strategy instance based on training type.
+
+        Args:
+            train_type: Type of training ("seq", "sft", "dpo", "grpo")
+            model: Model instance for the strategy
+            device: Device to run the strategy on
+            **kwargs: Additional arguments passed to strategy constructor
+
+        Returns:
+            Strategy instance
+        """
+        return super().create(train_type, model, device, **kwargs)
+
+    @classmethod
+    def available_strategies(cls) -> list:
+        """Return list of registered strategy names."""
+        return cls.list_registered()
+

 # ============== Strategy Classes ==============
 # All strategies are registered at class definition time using the decorator
@@ -144,13 +160,7 @@ class SEQStrategy(BaseStrategy):
    Computes cross-entropy loss for next token prediction.
    """

-    def __init__(
-        self,
-        model: Union[nn.Module, Callable[..., Dict[str, Tensor]]],
-        device: str,
-        label_smoothing: float = 0.0,
-        **kwargs,
-    ):
+    def __init__(self, model, device, label_smoothing: float = 0.0, **kwargs):
        super().__init__(model, device, **kwargs)
        self.label_smoothing = label_smoothing

@@ -175,31 +185,21 @@ class SFTStrategy(BaseStrategy):
    Applies cross-entropy loss only to tokens where loss_mask is True.
    """

-    def __init__(
-        self,
-        model: Union[nn.Module, Callable[..., Dict[str, Tensor]]],
-        device: str,
-        label_smoothing: float = 0.0,
-        **kwargs,
-    ):
+    def __init__(self, model, device, label_smoothing: float = 0.0, **kwargs):
        super().__init__(model, device, **kwargs)
        self.label_smoothing = label_smoothing

    def compute_loss(self, batch: Dict[str, Tensor]) -> Tensor:
        batch = move_to_device(batch, self.device)
-        input_ids, target_ids, position_ids, loss_mask = (
+        input_ids, target_ids, loss_mask = (
            batch["input_ids"],
            batch["target_ids"],
-            batch["position_ids"],
            batch["loss_mask"],
        )

        ignore_index = -100
-        input_mask = make_doc_boundary_mask(position_ids)
-        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"]
+        logits = self.model(input_ids=input_ids)["logits"]
+        target_ids = target_ids.masked_fill(loss_mask == 0, ignore_index)

        loss = F.cross_entropy(
            input=logits.flatten(0, 1).float(),
@@ -228,9 +228,7 @@ class DPOStrategy(BaseStrategy):
        **kwargs,
    ):
        super().__init__(model, device, **kwargs)
-        self.ref_model = create_ref_model(
-            self.model_fn, self.executor.unwrap_model(model)
-        ).to(device=self.device)
+        self.ref_model = create_ref_model(model)
        self.beta = beta
        self.reduction = reduction

@@ -284,9 +282,7 @@ class GRPOStrategy(BaseStrategy):
        **kwargs,
    ):
        super().__init__(model, device, **kwargs)
-        self.ref_model = create_ref_model(
-            self.model_fn, self.executor.unwrap_model(model)
-        ).to(device=self.device)
+        self.ref_model = create_ref_model(model)
        self.clip_eps = clip_eps
        self.kl_coef = kl_coef
        self.group_size = group_size
@@ -296,7 +292,8 @@ class GRPOStrategy(BaseStrategy):

    def sync_ref_model(self):
        """Copy current model weights to ref model."""
-        self.ref_model.load_state_dict(self.executor.unwrap_model(self.model))
+        ref_state = self.model.state_dict()
+        self.ref_model.load_state_dict(ref_state)

    def compute_loss(self, batch: Dict[str, Tensor]) -> Tensor:
        self._step += 1
@@ -1,23 +1,28 @@
 import json
 import logging
 import os
-import sys
 import time
 from pathlib import Path
-from typing import IO, Callable, List, Optional, Protocol, runtime_checkable
+from typing import 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

 from astrai.factory import BaseFactory
 from astrai.parallel import only_on_rank
-from astrai.parallel.setup import get_current_device, get_rank
+from astrai.parallel.setup import get_current_device
 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,
@@ -45,15 +50,18 @@ class TrainCallback(Protocol):
    def on_epoch_end(self, context: TrainContext):
        """Called at the end of each epoch."""

+    def on_step_begin(self, context: TrainContext):
+        """Called at the beginning of each step."""
+
+    def on_step_end(self, context: TrainContext):
+        """Called at the end of each step."""
+
    def on_batch_begin(self, context: TrainContext):
        """Called at the beginning of each batch."""

    def on_batch_end(self, context: TrainContext):
        """Called at the end of each batch."""

-    def on_optimizer_step(self, context: TrainContext):
-        """Called on every optimizer step (sync step only)."""
-
    def on_error(self, context: TrainContext):
        """Called when an error occurs during training."""

@@ -79,10 +87,8 @@ class GradientClippingCallback(TrainCallback):
    def __init__(self, max_grad_norm: float):
        self.max_grad_norm = max_grad_norm

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


@CallbackFactory.register("gradient_checkpointing")
@@ -133,41 +139,51 @@ class CheckpointCallback(TrainCallback):
        save_dir: str,
        interval: int,
        weight_only: bool = False,
+        state_dict_fn: Optional[Callable[[nn.Module], dict]] = None,
        save_extra_fn: Optional[Callable[["TrainContext"], dict]] = None,
+        load_extra_fn: Optional[Callable[[dict, "TrainContext"], None]] = None,
    ):
        self.save_dir = save_dir
        self.interval = interval
        self.weight_only = weight_only
+        self.state_dict_fn = state_dict_fn
        self.save_extra_fn = save_extra_fn or CheckpointCallback.save_extra
-        self.last_ckpt_step = 0
+        self.load_extra_fn = load_extra_fn or CheckpointCallback.load_extra
+        self.last_ckpt_iter = 0

+    @only_on_rank(0)
    def _save_checkpoint(self, context: TrainContext):
-        state_dict = context.executor.unwrap_model(context.model)
-        self.last_ckpt_step = context.optimizer_step
+        save_path = os.path.join(
+            self.save_dir, f"epoch_{context.epoch}_iter_{context.iteration}"
+        )
+        state_dict = (
+            self.state_dict_fn(context.model)
+            if self.state_dict_fn
+            else context.model.state_dict()
+        )

-        if get_rank() == 0:
-            save_path = os.path.join(
-                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,
-                consumed_samples=context.consumed_samples,
-                config=context.model_config,
-                extra=extra,
-                meta=meta,
-            )
-            context.checkpoint.save(save_path)
+        extra = self.save_extra_fn(context)
+        context.checkpoint = Checkpoint(
+            state_dict=state_dict,
+            epoch=context.epoch,
+            iteration=context.iteration,
+            extra=extra,
+            meta=context.config.to_dict(),
+        )
+
+        context.checkpoint.save(save_path)
+        self.last_ckpt_iter = context.iteration
+
+    def on_train_begin(self, context: TrainContext):
+        if context.checkpoint and context.checkpoint.extra:
+            self.load_extra_fn(context.checkpoint.extra, context)

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

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

    def on_error(self, context: TrainContext):
@@ -182,6 +198,12 @@ class CheckpointCallback(TrainCallback):
                extra[name] = obj.state_dict()
        return extra

+    @staticmethod
+    def load_extra(extra: dict, context: TrainContext):
+        for name in CheckpointCallback.extra_keys:
+            if name in extra:
+                getattr(context, name).load_state_dict(extra[name])
+

@CallbackFactory.register("progress_bar")
 class ProgressBarCallback(TrainCallback):
@@ -189,37 +211,28 @@ class ProgressBarCallback(TrainCallback):
    Progress bar callback for trainer.
    """

-    def __init__(
-        self, num_epoch: int, log_interval: int = 100, file: Optional[IO[str]] = None
-    ):
+    def __init__(self, num_epoch: int):
        self.num_epoch = num_epoch
-        self.log_interval = log_interval
-        self.file = file
        self.progress_bar: tqdm = None

    @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(
-            total=total_steps,
+            context.dataloader,
            desc=f"Epoch {context.epoch + 1}/{self.num_epoch}",
            dynamic_ncols=True,
-            file=self.file or sys.stdout,
        )

    @only_on_rank(0)
-    def on_optimizer_step(self, context: TrainContext):
-        self.progress_bar.update(1)
+    def on_batch_end(self, context: TrainContext):
        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:
+        if context.val_loss > 0:
            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):
@@ -228,20 +241,19 @@ class ProgressBarCallback(TrainCallback):
            self.progress_bar.close()


-@CallbackFactory.register("metric")
-class MetricCallback(TrainCallback):
+@CallbackFactory.register("metric_logger")
+class MetricLoggerCallback(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_flush_step = 0
+        self.last_log_iter = 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)
@@ -253,28 +265,53 @@ class MetricCallback(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):
+    def _get_log_data(self, context: TrainContext):
        return {
-            m: self._metric_funcs[m](context)
-            for m in names
-            if self._metric_funcs[m](context) is not None
+            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "epoch": context.epoch,
+            "iter": context.iteration,
+            **{m: self._metric_funcs[m](context) for m in self.metrics},
        }

    @only_on_rank(0)
-    def _append(self, event_type: str, context: TrainContext, **extra):
-        entry = {
-            "type": event_type,
-            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
-            "epoch": context.epoch,
-            "step": context.optimizer_step,
-            "consumed_samples": context.consumed_samples,
-            **extra,
-        }
-        self.log_cache.append(entry)
+    def _add_log(self, log_data):
+        self.log_cache.append(log_data)

-    def _run_validation(self, context: TrainContext) -> float:
+    @only_on_rank(0)
+    def _save_log(self, epoch, iter):
+        log_file = self.log_dir / f"epoch_{epoch}_iter_{iter}_metric.jsonl"
+
+        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:
+            log_data = self._get_log_data(context)
+            self._add_log(log_data)
+
+        if context.iteration - self.last_log_iter >= self.save_interval:
+            self._save_log(context.epoch, context.iteration)
+            self.last_log_iter = context.iteration
+
+    def on_train_end(self, context):
+        if context.iteration != self.last_log_iter:
+            self._save_log(context.epoch, context.iteration)
+
+    def on_error(self, context):
+        self._save_log(context.epoch, context.iteration)
+
+
+@CallbackFactory.register("validation")
+class ValidationCallback(TrainCallback):
+    def _run_validation(self, context: TrainContext):
        context.model.eval()

        total_loss = 0.0
@@ -286,49 +323,27 @@ class MetricCallback(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():
-            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)
+            loss_tensor = torch.tensor([avg_loss], device=get_current_device())
+            dist.all_reduce(loss_tensor, op=dist.ReduceOp.AVG)
+            avg_loss = loss_tensor.item()

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

-    @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")
+        step_count = context.iteration // context.config.grad_accum_steps
+        logger.info(
+            f"Epoch {context.epoch + 1}, Step {step_count}, Val Loss: {avg_loss:.4f}"
+        )

-    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)
+    def on_step_end(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)
@@ -1,18 +1,15 @@
 from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Dict, Optional, Self
+from typing import Optional, Self

-import torch
 import torch.nn as nn
-from torch.utils.data import DataLoader, random_split
+from torch.optim import Optimizer
+from torch.optim.lr_scheduler import LRScheduler
+from torch.utils.data import DataLoader

 from astrai.config.train_config import TrainConfig
 from astrai.dataset import ResumableDistributedSampler
-from astrai.model.components.lora import inject_lora
-from astrai.parallel.executor import BaseExecutor, ExecutorFactory
 from astrai.parallel.setup import get_current_device, get_rank, get_world_size
-from astrai.protocols import OptimizerProtocol, SchedulerProtocol
-from astrai.serialization import Checkpoint, load_json
+from astrai.serialization import Checkpoint
 from astrai.trainer.strategy import BaseStrategy, StrategyFactory


@@ -21,31 +18,20 @@ class TrainContext:
    model: nn.Module = field(default=None)
    strategy: BaseStrategy = field(default=None)
    dataloader: DataLoader = field(default=None)
-    optimizer: OptimizerProtocol = field(default=None)
-    scheduler: SchedulerProtocol = field(default=None)
+    optimizer: Optimizer = field(default=None)
+    scheduler: LRScheduler = field(default=None)
    checkpoint: Checkpoint = field(default=None)
    config: TrainConfig = field(default=None)
-    model_config: dict = field(default_factory=dict)
-    executor: BaseExecutor = field(default=None)

    epoch: int = field(default=0)
-    consumed_samples: int = field(default=0)
+    iteration: 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)
+    val_dataloader: DataLoader = field(default=None)
+    val_loss: float = field(default=0.0)

    world_size: int = field(default=1)
    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
-        )
+    kwargs: dict = field(default_factory=dict)


 class TrainContextBuilder:
@@ -54,88 +40,49 @@ class TrainContextBuilder:
        config: TrainConfig,
    ):
        self.config = config
-        self._resume_dir: Optional[str] = None
+        self._checkpoint: Optional[Checkpoint] = None

-    def with_resume_dir(self, resume_dir: Optional[str]) -> Self:
-        self._resume_dir = resume_dir
+    def with_checkpoint(self, checkpoint: Optional[Checkpoint]) -> Self:
+        self._checkpoint = checkpoint
        return self

    def build(self) -> TrainContext:
-        cfg = self.config
-        device = get_current_device()
-
-        executor = ExecutorFactory.create(
-            cfg.parallel_mode,
-            grad_accum_steps=cfg.grad_accum_steps,
-            **cfg.executor_kwargs,
-        )
-
-        model = cfg.model_fn()
-        model = model.to(device=device)
-
-        model_config = {}
-        if self._resume_dir:
-            config_path = Path(self._resume_dir) / "config.json"
-            if config_path.exists():
-                model_config = load_json(config_path)
-
-        if not model_config and hasattr(model, "config"):
-            model_config = model.config.to_dict()
-
        context = TrainContext(
-            model=model,
+            model=self.config.model,
            world_size=get_world_size(),
            rank=get_rank(),
-            config=cfg,
-            model_config=model_config,
-            executor=executor,
+            config=self.config,
        )

-        if self._resume_dir:
-            checkpoint = Checkpoint.load_any(self._resume_dir)
-            if checkpoint is not None:
-                model.load_state_dict(checkpoint.state_dict, strict=False)
-                if checkpoint.config:
-                    context.model_config = checkpoint.config
-                context.epoch = checkpoint.epoch or cfg.start_epoch
-                if checkpoint.consumed_samples > 0:
-                    context.consumed_samples = checkpoint.consumed_samples
-                else:
-                    context.consumed_samples = cfg.start_samples * context.world_size
-                context.checkpoint = checkpoint
+        device = get_current_device()
+        context.model = context.model.to(device=device)

-        if cfg.lora is not None:
-            inject_lora(
-                model,
-                r=cfg.lora.r,
-                alpha=cfg.lora.alpha,
-                target_modules=set(cfg.lora.target_modules),
+        if self.config.nprocs > 1 and self.config.parallel_wrapper:
+            context.model = self.config.parallel_wrapper(context.model)
+
+        if self._checkpoint is not None:
+            context.epoch = max(self._checkpoint.epoch, self.config.start_epoch)
+            context.iteration = max(self._checkpoint.iteration, self.config.start_batch)
+            context.model.load_state_dict(self._checkpoint.state_dict)
+            context.checkpoint = self._checkpoint
+        else:
+            context.checkpoint = Checkpoint(
+                state_dict=context.model.state_dict(),
            )

-        context.optimizer = cfg.optimizer_fn(model)
-        context.scheduler = cfg.scheduler_fn(context.optimizer)
+        context.optimizer = self.config.optimizer_fn(context.model)
+        context.scheduler = self.config.scheduler_fn(context.optimizer)

-        train_dataset = cfg.dataset
-        val_dataset = cfg.val_dataset
-
-        if val_dataset is None and cfg.val_split is not None:
-            n_total = len(cfg.dataset)
-            n_val = max(1, int(n_total * cfg.val_split))
-            n_train = n_total - n_val
-            generator = torch.Generator().manual_seed(cfg.random_seed)
-            train_dataset, val_dataset = random_split(
-                cfg.dataset, [n_train, n_val], generator=generator
-            )
-
-        sampler_offset = context.consumed_samples // context.world_size
+        cfg = self.config
+        sampler_offset = context.iteration * cfg.batch_per_device
        sampler = ResumableDistributedSampler(
-            data_source=train_dataset,
+            data_source=cfg.dataset,
            start_epoch=context.epoch,
            start_iter=sampler_offset,
            seed=cfg.random_seed,
        )
        context.dataloader = DataLoader(
-            train_dataset,
+            cfg.dataset,
            batch_size=cfg.batch_per_device,
            sampler=sampler,
            num_workers=cfg.num_workers,
@@ -143,16 +90,16 @@ class TrainContextBuilder:
            prefetch_factor=cfg.prefetch_factor,
        )

-        if val_dataset is not None:
+        if cfg.val_dataset is not None:
            val_sampler = ResumableDistributedSampler(
-                data_source=val_dataset,
+                data_source=cfg.val_dataset,
                start_epoch=0,
                start_iter=0,
                seed=cfg.random_seed,
                shuffle=False,
            )
            context.val_dataloader = DataLoader(
-                val_dataset,
+                cfg.val_dataset,
                batch_size=cfg.batch_per_device,
                sampler=val_sampler,
                num_workers=cfg.num_workers,
@@ -160,30 +107,11 @@ class TrainContextBuilder:
                prefetch_factor=cfg.prefetch_factor,
            )

-        context.model, context.optimizer, context.dataloader, context.scheduler = (
-            executor.prepare(
-                model,
-                context.optimizer,
-                context.dataloader,
-                context.scheduler,
-            )
-        )
-
-        if context.checkpoint and context.checkpoint.extra:
-            extra = context.checkpoint.extra
-            for name in ("optimizer", "scheduler"):
-                if name in extra:
-                    obj = getattr(context, name, None)
-                    if obj is not None:
-                        obj.load_state_dict(extra[name])
-
        context.strategy = StrategyFactory.create(
-            cfg.strategy,
            model=context.model,
+            train_type=self.config.strategy,
            device=device,
-            executor=executor,
-            model_fn=cfg.model_fn,
-            **cfg.extra_kwargs,
+            **self.config.extra_kwargs,
        )

        return context
@@ -3,6 +3,7 @@ from typing import List, Optional

 from astrai.config import TrainConfig
 from astrai.parallel.setup import spawn_parallel_fn
+from astrai.serialization import Checkpoint
 from astrai.trainer.train_callback import (
    CallbackFactory,
    TrainCallback,
@@ -33,16 +34,12 @@ class Trainer:
                "checkpoint",
                cfg.ckpt_dir,
                cfg.ckpt_interval,
-            ),
-            CallbackFactory.create(
-                "metric",
-                log_dir=cfg.log_dir,
-                save_interval=cfg.ckpt_interval,
-                metrics=cfg.metrics,
-                val_step=cfg.val_step,
+                state_dict_fn=cfg.state_dict_fn,
            ),
            CallbackFactory.create("progress_bar", cfg.n_epoch),
+            CallbackFactory.create("metric_logger", cfg.ckpt_dir, cfg.ckpt_interval),
            CallbackFactory.create("gradient_clipping", cfg.max_grad_norm),
+            CallbackFactory.create("validation"),
        ]
        return callbacks

@@ -52,50 +49,47 @@ class Trainer:
            if method:
                method(context)

-    def _trainer_loop(self, resume_dir: Optional[str] = None):
-        context = (
-            TrainContextBuilder(self.train_config).with_resume_dir(resume_dir).build()
-        )
-        executor = context.executor
+    def _trainer_loop(self, checkpoint: Optional[Checkpoint] = None):
+        cfg = self.train_config
+        context = TrainContextBuilder(cfg).with_checkpoint(checkpoint).build()
        self._call_callbacks("on_train_begin", context)

        try:
            context.model.train()
+            grad_accum_steps = cfg.grad_accum_steps

-            for epoch in range(context.epoch, context.config.n_epoch):
+            for epoch in range(context.epoch, cfg.n_epoch):
                context.epoch = epoch
                self._call_callbacks("on_epoch_begin", context)

                for batch in context.dataloader:
-                    with executor.accumulate(context.model):
-                        self._call_callbacks("on_batch_begin", context)
-                        loss = context.strategy(batch)
-                        context.loss = loss.item()
-                        stand_loss = loss / executor.grad_accum_steps
-                        executor.backward(stand_loss)
-                        context.consumed_samples += (
-                            context.config.batch_per_device * context.world_size
-                        )
-                        self._call_callbacks("on_batch_end", context)
+                    self._call_callbacks("on_batch_begin", context)
+                    loss = context.strategy(batch)
+                    context.loss = loss.item()
+                    stand_loss = loss / grad_accum_steps
+                    stand_loss.backward()
+                    context.iteration += 1
+                    self._call_callbacks("on_batch_end", context)

-                        if executor.sync_gradients:
-                            self._call_callbacks("on_optimizer_step", context)
-                            context.optimizer.step()
-                            context.optimizer.zero_grad()
+                    if context.iteration % grad_accum_steps == 0:
+                        self._call_callbacks("on_step_begin", context)
+                        context.optimizer.step()
+                        context.optimizer.zero_grad()
+                        self._call_callbacks("on_step_end", context)

-                            if context.scheduler:
-                                context.scheduler.step()
+                        if context.scheduler:
+                            context.scheduler.step()

                self._call_callbacks("on_epoch_end", context)

        except Exception as e:
-            logger.error("Training failed: %s", str(e), exc_info=True)
+            logger.error(f"Training failed: {str(e)}", exc_info=True)
            self._call_callbacks("on_error", context)
            raise
        finally:
            self._call_callbacks("on_train_end", context)

-    def train(self, resume_dir: Optional[str] = None):
+    def train(self, checkpoint: Optional[Checkpoint] = None):
        cfg = self.train_config
        spawn_parallel_fn(
            self._trainer_loop,
@@ -105,5 +99,5 @@ class Trainer:
            master_port=cfg.master_port,
            device_type=cfg.device_type,
            start_method=cfg.start_method,
-            resume_dir=resume_dir,
+            checkpoint=checkpoint,
        )
@@ -1,13 +1,12 @@
 services:
  server:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    user: "${UID:-1000}:${GID:-1000}"
+    build: .
+    image: astrai:latest
    ports:
      - "8000:8000"
    volumes:
      - ./params:/app/params:ro
+      - ./checkpoints:/app/checkpoints
    command: python -m scripts.tools.server --port 8000 --device cuda
    deploy:
      resources:
@@ -26,14 +25,13 @@ services:

  server-cpu:
    profiles: [cpu]
-    build:
-      context: .
-      dockerfile: Dockerfile
-    user: "${UID:-1000}:${GID:-1000}"
+    build: .
+    image: astrai:latest
    ports:
      - "8000:8000"
    volumes:
      - ./params:/app/params:ro
+      - ./checkpoints:/app/checkpoints
    command: python -m scripts.tools.server --port 8000 --device cpu
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
@@ -9,8 +9,8 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
    "h5py==3.15.1",
-    "numpy==2.4.4",
-    "torch==2.11.0",
+    "numpy==2.3.2",
+    "torch==2.7.1",
    "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/cu128"
+extra-index-url = "https://download.pytorch.org/whl/cu126"

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

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

 PROJECT_ROOT = Path(__file__).resolve().parents[2]
-
-
-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()
+PARAMETER_ROOT = Path(PROJECT_ROOT, "params")


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

-    messages = [{"role": "system", "content": args.system_prompt}]
+    messages = [{"role": "system", "content": "You are a helpful assistant."}]
+    engine = InferenceEngine(model=model, tokenizer=tokenizer)

    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=args.max_tokens,
-            temperature=args.temperature,
-            top_p=args.top_p,
-            top_k=args.top_k,
+            max_tokens=2048,
+            temperature=0.8,
+            top_p=0.95,
+            top_k=50,
        ):
            print(token, end="", flush=True)
            full_response += token

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


@@ -16,7 +16,6 @@ NC='\033[0m' # No Color
 IMAGE_NAME="astrai"
 IMAGE_TAG="latest"
 REGISTRY=""
-CONTAINER_ID=""

 # Print colored messages
 print_info() {
@@ -176,10 +175,6 @@ main() {
                PORT="$2"
                shift 2
                ;;
-            --container)
-                CONTAINER_ID="$2"
-                shift 2
-                ;;
            --gpu)
                GPU=true
                shift
@@ -202,7 +197,6 @@ main() {
                echo "  --dockerfile FILE  Dockerfile path (default: Dockerfile)"
                echo "  --context PATH     Build context (default: .)"
                echo "  --port PORT        Port for run (default: 8000)"
-                echo "  --container ID     Container ID for logs"
                echo "  --gpu              Enable GPU support"
                echo "  --help             Show this help message"
                echo ""
@@ -211,7 +205,6 @@ main() {
                echo "  $0 build --tag v1.0.0"
                echo "  $0 run --port 8080"
                echo "  $0 run --gpu"
-                echo "  $0 logs --container abc123"
                echo "  $0 push --registry ghcr.io/username"
                exit 0
                ;;
@@ -244,7 +237,7 @@ main() {
            show_info
            ;;
        logs)
-            show_logs "$CONTAINER_ID"
+            show_logs "$2"
            ;;
        "")
            print_error "No command specified. Use --help for usage"
@@ -1,307 +0,0 @@
-"""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,393 +0,0 @@
-"""HumanEval benchmark — functional pipeline design.
-
-Pipeline:
-    load -> generate -> extract -> test -> score -> report
-
-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 typing import Dict, Iterator, List, Optional, Sequence, Tuple
-
-import numpy as np
-import torch
-import tqdm
-
-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 = [
-    "\nclass ",
-    "\ndef ",
-    "\n# ",
-    "\nif __name__",
-    "\nprint(",
-    "\n\n\n",
-]
-
-
-@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(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(path, "wb") as f_out:
-            f_out.write(f_in.read())
-    os.remove(tmp)
-    print(f"  saved to {path}")
-
-
-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:
-                rows.append(json.loads(line))
-    return rows
-
-
-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:
-        return code
-
-    lines = code[match.end() :].split("\n")
-    body_lines = []
-    started = False
-
-    for line in lines:
-        stripped = line.rstrip()
-        if not stripped and not started:
-            continue
-        if not stripped and started:
-            body_lines.append("")
-            continue
-        if not started:
-            started = True
-        if stripped.lstrip() == stripped and started:
-            break
-        body_lines.append(stripped)
-
-    body = "\n".join(body_lines)
-    return body if body.strip() else None
-
-
-def deduplicate(seq: Sequence[str]) -> List[str]:
-    seen = set()
-    return [x for x in seq if not (x in seen or seen.add(x))]
-
-
-def generate_batch(
-    engine: InferenceEngine,
-    prompt: str,
-    n: int,
-    batch_size: int,
-    max_tokens: int,
-    temperature: float,
-    top_p: float,
-    top_k: int,
-) -> List[str]:
-    completions = []
-    remaining = n
-    while remaining > 0:
-        current = min(batch_size, remaining)
-        outputs = engine.generate(
-            prompt=[prompt] * current,
-            stream=False,
-            max_tokens=max_tokens,
-            temperature=temperature,
-            top_p=top_p,
-            top_k=top_k,
-        )
-        completions.extend(outputs if isinstance(outputs, list) else [outputs])
-        remaining -= current
-    return deduplicate(completions)
-
-
-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: Sequence[dict],
-    cfg: EvalConfig,
-) -> List[dict]:
-    results = []
-    for problem in tqdm.tqdm(problems, desc="Generating", unit="problem"):
-        raw = generate_batch(
-            engine,
-            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,
-            )
-        )
-    return results
-
-
-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=None,
-        help="Skip generation, test existing completions JSON",
-    )
-    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)
-
-    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,
-        test_workers=args.test_workers,
-        test_timeout=args.test_timeout,
-        problem_indices=args.problems,
-    )
-
-
-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
-
-
-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__":
-    main()
@@ -1,474 +0,0 @@
-"""IFD (Instruction Following Difficulty) data quality scoring.
-
-IFD = conditional_NLL / unconditional_NLL
-
- Messages format: plain text concatenation (no chat template)
- Plain format: raw instr_key + resp_key fields
-
-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
-import tqdm
-
-from astrai.model import AutoModel
-from astrai.tokenize import AutoTokenizer
-
-
-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,
-    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,
-            "skip_reason": "empty ctx or resp",
-        }
-    return _score_batch(
-        [(ctx_ids, resp_ids)],
-        model,
-        device,
-        max_len,
-        sentinel_ids=sentinel_ids,
-        per_token=per_token,
-    )[0]
-
-
-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
-    )
-    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 {
-        "ifd": avg,
-        "ifd_detail": valid[0] if len(valid) == 1 else None,
-        "ifd_turns": raw_scores,
-    }
-
-
-def process_file(
-    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,
-):
-    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()
-
-    sentinel_ids = _resolve_sentinel_ids(tokenizer, sentinel_text)
-
-    with open(input_file, encoding="utf-8") as f:
-        data = [json.loads(line) for line in f if line.strip()]
-
-    results = []
-    all_ifds = []
-    buffer = []
-
-    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,
-                device,
-                max_len,
-                sentinel_ids,
-                per_token,
-            )
-
-    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 all_ifds if v is not None]
-    if valid_ifd:
-        print(f"\n{'=' * 50}")
-        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"
-    )
-    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(
-        "--format",
-        type=str,
-        default="plain",
-        choices=["plain", "messages"],
-        help="Input format",
-    )
-    parser.add_argument(
-        "--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="\n",
-        help='Plain-text prefix for unconditional pass (default: "\\n"). Use "" for bos/pad fallback.',
-    )
-    parser.add_argument(
-        "--per_token",
-        action="store_true",
-        help="Include per-token IFD breakdown in output",
-    )
-    args = parser.parse_args()
-
-    process_file(
-        args.param_path,
-        args.input,
-        args.output,
-        args.instr_key,
-        args.resp_key,
-        args.max_len,
-        data_format=args.format,
-        batch_size=args.batch_size,
-        device=args.device,
-        sentinel_text=args.sentinel_text,
-        per_token=args.per_token,
-    )
-
-
-if __name__ == "__main__":
-    main()
@@ -1,609 +0,0 @@
-"""IFEval instruction-following evaluation benchmark.
-
-Evaluates model responses against regex-based constraint verifiers.
-Supports all IFEval constraint types except language detection.
-
-Usage::
-
-    python scripts/tools/evaluate_ifeval.py --param_path ./params \
-        --data_path ifeval.jsonl --output results.json \
-        --temperature 0.1 --max_tokens 512
-"""
-
-import argparse
-import json
-import os
-import re
-import urllib.request
-from typing import Callable, Dict, List, Optional
-
-import torch
-import tqdm
-
-from astrai.inference import InferenceEngine
-from astrai.model import AutoModel
-from astrai.tokenize import AutoTokenizer
-
-IFEVAL_URL = (
-    "https://raw.githubusercontent.com/google-research/"
-    "google-research/master/instruction_following_eval/data/input_data.jsonl"
-)
-
-CONSTRAINT_VERIFIERS: Dict[str, Callable[[str, dict], bool]] = {}
-
-
-def register(instruction_id: str):
-    def decorator(fn):
-        CONSTRAINT_VERIFIERS[instruction_id] = fn
-        return fn
-
-    return decorator
-
-
-@register("keywords:existence")
-def check_keyword_existence(response: str, kwargs: dict) -> bool:
-    for kw in kwargs["keywords"]:
-        if not re.search(re.escape(kw), response, re.IGNORECASE):
-            return False
-    return True
-
-
-@register("keywords:frequency")
-def check_keyword_frequency(response: str, kwargs: dict) -> bool:
-    keyword = kwargs["keyword"]
-    frequency = kwargs.get("frequency", 1)
-    relation = kwargs.get("relation", "at least")
-    count = len(re.findall(re.escape(keyword), response, re.IGNORECASE))
-    if relation == "less than":
-        return count < frequency
-    return count >= frequency
-
-
-@register("keywords:forbidden_words")
-def check_forbidden_words(response: str, kwargs: dict) -> bool:
-    for word in kwargs["forbidden_words"]:
-        if re.search(r"\b" + re.escape(word) + r"\b", response, re.IGNORECASE):
-            return False
-    return True
-
-
-@register("keywords:letter_frequency")
-def check_letter_frequency(response: str, kwargs: dict) -> bool:
-    letter = kwargs["letter"].lower()
-    frequency = kwargs.get("let_frequency", 1)
-    relation = kwargs.get("let_relation", "at least")
-    count = response.lower().count(letter)
-    if relation == "less than":
-        return count < frequency
-    return count >= frequency
-
-
-@register("detectable_content:number_placeholders")
-def check_placeholders(response: str, kwargs: dict) -> bool:
-    num = kwargs.get("num_placeholders", 1)
-    placeholders = re.findall(r"\[.*?\]", response)
-    return len(placeholders) >= num
-
-
-@register("detectable_content:postscript")
-def check_postscript(response: str, kwargs: dict) -> bool:
-    marker = kwargs.get("postscript_marker", "P.S.")
-    response_lower = response.lower()
-    if marker == "P.P.S":
-        return bool(re.search(r"p\.\s?p\.\s?s", response_lower))
-    elif marker == "P.S.":
-        return bool(re.search(r"p\.\s?s\.", response_lower))
-    else:
-        return bool(re.search(re.escape(marker.lower()), response_lower))
-
-
-@register("detectable_format:number_bullet_lists")
-def check_bullet_lists(response: str, kwargs: dict) -> bool:
-    num = kwargs.get("num_bullets", 1)
-    bullets = re.findall(r"^\s*\*[^\*].*$", response, re.MULTILINE)
-    dashes = re.findall(r"^\s*-.*$", response, re.MULTILINE)
-    return len(bullets) + len(dashes) == num
-
-
-@register("detectable_format:number_highlighted_sections")
-def check_highlighted_sections(response: str, kwargs: dict) -> bool:
-    num = kwargs.get("num_highlights", 1)
-    highlights = re.findall(r"\*[^\n\*]+\*", response)
-    count = 0
-    for h in highlights:
-        if h.strip("*").strip():
-            count += 1
-    return count >= num
-
-
-@register("detectable_format:multiple_sections")
-def check_multiple_sections(response: str, kwargs: dict) -> bool:
-    splitter = kwargs.get("section_spliter", "Section")
-    num = kwargs.get("num_sections", 1)
-    pattern = r"\s?" + re.escape(splitter) + r"\s?\d+\s?"
-    sections = re.split(pattern, response)
-    return len(sections) - 1 >= num
-
-
-@register("detectable_format:title")
-def check_title(response: str, kwargs: dict) -> bool:
-    titles = re.findall(r"<<[^>\n]+>>", response)
-    for title in titles:
-        if title.strip("<>").strip():
-            return True
-    return False
-
-
-@register("detectable_format:json_format")
-def check_json_format(response: str, kwargs: dict) -> bool:
-    value = response.strip()
-    for prefix in ("```json", "```Json", "```JSON", "```"):
-        if value.lower().startswith(prefix.lower()):
-            value = value[len(prefix) :].strip()
-    if value.endswith("```"):
-        value = value[:-3].strip()
-    try:
-        json.loads(value)
-        return True
-    except (ValueError, json.JSONDecodeError):
-        return False
-
-
-@register("detectable_format:general_punctuation")
-def check_general_punctuation(response: str, kwargs: dict) -> bool:
-    punctuation_blacklist = kwargs.get("punctuation_blacklist", [])
-    for punct in punctuation_blacklist:
-        if punct in response:
-            return False
-    return True
-
-
-@register("detectable_format:number_highlighted_words")
-def check_highlighted_words(response: str, kwargs: dict) -> bool:
-    num = kwargs.get("num_highlights", 1)
-    highlights = re.findall(r"\*[^\s\*][^\*]*[^\s\*]\*", response)
-    return len(highlights) >= num
-
-
-@register("startend:end_checker")
-def check_end_checker(response: str, kwargs: dict) -> bool:
-    end_phrase = kwargs["end_phrase"]
-    return (
-        response.strip()
-        .rstrip('"')
-        .rstrip()
-        .lower()
-        .endswith(end_phrase.strip().lower())
-    )
-
-
-@register("startend:quotation")
-def check_quotation(response: str, kwargs: dict) -> bool:
-    value = response.strip()
-    return value.startswith('"') and value.endswith('"')
-
-
-@register("startend:start_checker")
-def check_start_checker(response: str, kwargs: dict) -> bool:
-    starter = kwargs["starter"]
-    return bool(re.search(r"^\s*" + re.escape(starter), response, re.MULTILINE))
-
-
-@register("change_case:english_capital")
-def check_english_capital(response: str, kwargs: dict) -> bool:
-    return response.isupper()
-
-
-@register("change_case:english_lowercase")
-def check_english_lowercase(response: str, kwargs: dict) -> bool:
-    return response.islower()
-
-
-@register("change_case:capital_word_frequency")
-def check_capital_word_frequency(response: str, kwargs: dict) -> bool:
-    frequency = kwargs.get("capital_frequency", 1)
-    relation = kwargs.get("capital_relation", "at least")
-    capital_words = re.findall(r"\b[A-Z]{2,}\b", response)
-    count = len(capital_words)
-    if relation == "less than":
-        return count < frequency
-    return count >= frequency
-
-
-@register("punctuation:no_comma")
-def check_no_comma(response: str, kwargs: dict) -> bool:
-    return "," not in response
-
-
-def count_words(text: str) -> int:
-    return len(re.findall(r"\b\w+\b", text))
-
-
-def count_sentences(text: str) -> int:
-    text = text.strip()
-    if not text:
-        return 0
-    sentences = re.split(r"(?<=[.!?])\s+", text)
-    return len([s for s in sentences if s.strip()])
-
-
-@register("length_constraints:number_words")
-def check_number_words(response: str, kwargs: dict) -> bool:
-    num = kwargs.get("num_words", 100)
-    relation = kwargs.get("relation", "at least")
-    cnt = count_words(response)
-    if relation == "less than":
-        return cnt < num
-    return cnt >= num
-
-
-@register("length_constraints:number_sentences")
-def check_number_sentences(response: str, kwargs: dict) -> bool:
-    num = kwargs.get("num_sentences", 5)
-    relation = kwargs.get("relation", "at least")
-    cnt = count_sentences(response)
-    if relation == "less than":
-        return cnt < num
-    return cnt >= num
-
-
-@register("length_constraints:number_paragraphs")
-def check_number_paragraphs(response: str, kwargs: dict) -> bool:
-    num = kwargs.get("num_paragraphs", 1)
-    if "***" in response:
-        paragraphs = re.split(r"\s?\*\*\*\s?", response)
-    else:
-        paragraphs = re.split(r"\n\n+", response)
-    actual = len([p for p in paragraphs if p.strip()])
-    return actual == num
-
-
-@register("length_constraints:nth_paragraph_first_word")
-def check_nth_paragraph_first_word(response: str, kwargs: dict) -> bool:
-    num_paragraphs = kwargs.get("num_paragraphs", 1)
-    nth = kwargs.get("nth_paragraph", 1)
-    first_word = kwargs.get("first_word", "").lower()
-
-    paragraphs = re.split(r"\n\n+", response)
-    paragraphs = [p.strip() for p in paragraphs if p.strip()]
-
-    if len(paragraphs) != num_paragraphs:
-        return False
-    if nth > len(paragraphs):
-        return False
-
-    target = paragraphs[nth - 1]
-    words = target.split()
-    if not words:
-        return False
-
-    word = words[0].strip().lstrip("'\"").rstrip(".,!?:;\"'")
-    return word.lower() == first_word
-
-
-@register("length_constraints:nth_word_checker")
-def check_nth_word(response: str, kwargs: dict) -> bool:
-    nth = kwargs.get("nth_word", 1)
-    target = kwargs.get("target_word", "").lower()
-    words = re.findall(r"\b\w+\b", response)
-    if nth > len(words):
-        return False
-    return words[nth - 1].lower() == target
-
-
-@register("combination:repeat_prompt")
-def check_repeat_prompt(response: str, kwargs: dict) -> bool:
-    prompt = kwargs["prompt_to_repeat"]
-    return response.strip().lower().startswith(prompt.strip().lower())
-
-
-@register("combination:two_responses")
-def check_two_responses(response: str, kwargs: dict) -> bool:
-    parts = response.split("******")
-    valid = [p for p in parts if p.strip()]
-    if len(valid) != 2:
-        return False
-    return valid[0].strip() != valid[1].strip()
-
-
-def download_ifeval(data_path: str):
-    if os.path.exists(data_path):
-        return
-    os.makedirs(os.path.dirname(data_path) or ".", exist_ok=True)
-    print(f"Downloading IFEval from {IFEVAL_URL} ...")
-    tmp = data_path + ".tmp"
-    urllib.request.urlretrieve(IFEVAL_URL, tmp)
-    with open(tmp, "rb") as f_in:
-        content = f_in.read()
-    with open(data_path, "wb") as f_out:
-        f_out.write(content)
-    os.remove(tmp)
-    print(f"  saved to {data_path}")
-
-
-def load_problems(data_path: str) -> List[dict]:
-    problems = []
-    with open(data_path, "r", encoding="utf-8") as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                problems.append(json.loads(line))
-    return problems
-
-
-def verify_response(response: str, instruction_id: str, kwargs: dict) -> Optional[bool]:
-    verifier = CONSTRAINT_VERIFIERS.get(instruction_id)
-    if verifier is None:
-        return None
-    try:
-        return verifier(response, kwargs)
-    except Exception:
-        return False
-
-
-def generate_one(
-    engine: InferenceEngine,
-    tokenizer: AutoTokenizer,
-    prompt: str,
-    max_tokens: int,
-    temperature: float,
-    top_p: float,
-    top_k: int,
-) -> str:
-    formatted = tokenizer.apply_chat_template(
-        [{"role": "user", "content": prompt}],
-        tokenize=False,
-        add_generation_prompt=True,
-    )
-    output = engine.generate(
-        prompt=formatted,
-        stream=False,
-        max_tokens=max_tokens,
-        temperature=temperature,
-        top_p=top_p,
-        top_k=top_k,
-    )
-    if isinstance(output, list):
-        return output[0]
-    return output
-
-
-def evaluate(
-    engine: InferenceEngine,
-    tokenizer: AutoTokenizer,
-    problems: List[dict],
-    max_tokens: int,
-    temperature: float,
-    top_p: float,
-    top_k: int,
-    num_samples: int = 1,
-) -> Dict:
-    results = {}
-    constraint_stats: Dict[str, Dict[str, int]] = {}
-    total_constraints = 0
-    total_passed = 0
-
-    for problem in tqdm.tqdm(problems, desc="IFEval", unit="problem"):
-        key = problem["key"]
-        prompt = problem["prompt"]
-        instruction_ids = problem["instruction_id_list"]
-        kwargs_list = problem["kwargs"]
-
-        samples = []
-        for _ in range(num_samples):
-            response = generate_one(
-                engine, tokenizer, prompt, max_tokens, temperature, top_p, top_k
-            )
-            samples.append(response)
-
-        constraint_results = []
-        passed = 0
-        verified = 0
-
-        for idx, instruction_id in enumerate(instruction_ids):
-            kwargs = kwargs_list[idx] if idx < len(kwargs_list) else {}
-            best_pass = False
-            for response in samples:
-                result = verify_response(response, instruction_id, kwargs)
-                if result is None:
-                    continue
-                if result:
-                    best_pass = True
-                    break
-
-            verifier_exists = instruction_id in CONSTRAINT_VERIFIERS
-            if verifier_exists:
-                verified += 1
-                if best_pass:
-                    passed += 1
-
-            constraint_results.append(
-                {
-                    "instruction_id": instruction_id,
-                    "passed": best_pass,
-                    "supported": verifier_exists,
-                    "kwargs": kwargs,
-                }
-            )
-
-            if verifier_exists:
-                if instruction_id not in constraint_stats:
-                    constraint_stats[instruction_id] = {
-                        "total": 0,
-                        "passed": 0,
-                    }
-                constraint_stats[instruction_id]["total"] += 1
-                if best_pass:
-                    constraint_stats[instruction_id]["passed"] += 1
-
-        total_constraints += verified
-        total_passed += passed
-
-        accuracy = passed / verified if verified > 0 else None
-        results[str(key)] = {
-            "key": key,
-            "prompt": prompt,
-            "response": samples[0],
-            "num_samples": num_samples,
-            "num_constraints": len(instruction_ids),
-            "num_verified": verified,
-            "num_passed": passed,
-            "accuracy": round(accuracy, 4) if accuracy is not None else None,
-            "constraints": constraint_results,
-        }
-
-    overall_accuracy = (
-        round(total_passed / total_constraints, 4) if total_constraints > 0 else 0.0
-    )
-
-    type_summary = {}
-    for inst_id, stats in sorted(constraint_stats.items()):
-        type_summary[inst_id] = {
-            "total": stats["total"],
-            "passed": stats["passed"],
-            "accuracy": round(stats["passed"] / stats["total"], 4)
-            if stats["total"] > 0
-            else 0.0,
-        }
-
-    unsupported_count = sum(
-        1
-        for p in problems
-        for iid in p["instruction_id_list"]
-        if iid not in CONSTRAINT_VERIFIERS
-    )
-
-    results["_summary"] = {
-        "total_problems": len(problems),
-        "total_constraints": total_constraints,
-        "total_passed": total_passed,
-        "overall_accuracy": overall_accuracy,
-        "unsupported_constraints": unsupported_count,
-        "supported_types": sorted(CONSTRAINT_VERIFIERS.keys()),
-        "per_type_accuracy": type_summary,
-    }
-
-    return results
-
-
-def main():
-    parser = argparse.ArgumentParser(description="IFEval benchmark")
-    parser.add_argument(
-        "--param_path", type=str, default="./params", help="Model directory"
-    )
-    parser.add_argument(
-        "--data_path",
-        type=str,
-        default="./ifeval/input_data.jsonl",
-        help="IFEval JSONL file (auto-download if missing)",
-    )
-    parser.add_argument("--output", type=str, default=None, help="Output JSON path")
-    parser.add_argument(
-        "--max_tokens", type=int, default=512, help="Max generation tokens"
-    )
-    parser.add_argument(
-        "--temperature",
-        type=float,
-        default=0.1,
-        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(
-        "--num_samples",
-        type=int,
-        default=1,
-        help="Number of samples per problem (best-of-n scoring)",
-    )
-    parser.add_argument(
-        "--batch_size", type=int, default=1, help="Inference batch size"
-    )
-    parser.add_argument(
-        "--limit",
-        type=int,
-        default=None,
-        help="Limit to first N problems (for quick testing)",
-    )
-    parser.add_argument(
-        "--dump_responses",
-        type=str,
-        default=None,
-        help="Path to dump raw model responses (JSONL)",
-    )
-    args = parser.parse_args()
-
-    download_ifeval(args.data_path)
-    problems = load_problems(args.data_path)
-    if args.limit:
-        problems = problems[: args.limit]
-
-    print(f"Loaded {len(problems)} problems")
-    print(f"Supported constraint types: {len(CONSTRAINT_VERIFIERS)}")
-
-    model = AutoModel.from_pretrained(args.param_path)
-    tokenizer = AutoTokenizer.from_pretrained(args.param_path)
-    model.to(device="cuda", dtype=torch.bfloat16)
-    model.eval()
-
-    engine = InferenceEngine(
-        model=model,
-        tokenizer=tokenizer,
-        max_batch_size=args.batch_size,
-    )
-
-    results = evaluate(
-        engine=engine,
-        tokenizer=tokenizer,
-        problems=problems,
-        max_tokens=args.max_tokens,
-        temperature=args.temperature,
-        top_p=args.top_p,
-        top_k=args.top_k,
-        num_samples=args.num_samples,
-    )
-
-    summary = results.pop("_summary")
-    print(f"\n{'=' * 60}")
-    print(f"  Problems:       {summary['total_problems']}")
-    print(f"  Constraints:    {summary['total_constraints']}")
-    print(f"  Passed:         {summary['total_passed']}")
-    print(f"  Accuracy:       {summary['overall_accuracy']:.2%}")
-    print(f"  Unsupported:    {summary['unsupported_constraints']}")
-    print(f"{'=' * 60}")
-
-    print("\nPer-type accuracy:")
-    for inst_id, stats in sorted(summary["per_type_accuracy"].items()):
-        print(
-            f"  {inst_id:50s}  {stats['accuracy']:.2%}  "
-            f"({stats['passed']}/{stats['total']})"
-        )
-
-    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"\nResults saved to {args.output}")
-
-    if args.dump_responses:
-        with open(args.dump_responses, "w", encoding="utf-8") as f:
-            for k, v in results.items():
-                if k.startswith("_"):
-                    continue
-                f.write(
-                    json.dumps(
-                        {
-                            "key": v["key"],
-                            "prompt": v["prompt"],
-                            "response": v["response"],
-                        },
-                        ensure_ascii=False,
-                    )
-                    + "\n"
-                )
-        print(f"Responses dumped to {args.dump_responses}")
-
-    engine.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,319 +0,0 @@
-"""MMLU evaluation via log-likelihood ranking."""
-
-import argparse
-import csv
-import json
-import os
-import shutil
-import tarfile
-
-import requests
-import torch
-import torch.nn.functional as F
-import tqdm
-
-from astrai.model import AutoModel
-from astrai.tokenize import AutoTokenizer
-
-MMLU_URL = "https://people.eecs.berkeley.edu/~hendrycks/data.tar"
-MMLU_SUBJECTS = [
-    "abstract_algebra",
-    "anatomy",
-    "astronomy",
-    "business_ethics",
-    "clinical_knowledge",
-    "college_biology",
-    "college_chemistry",
-    "college_computer_science",
-    "college_mathematics",
-    "college_medicine",
-    "college_physics",
-    "computer_security",
-    "conceptual_physics",
-    "econometrics",
-    "electrical_engineering",
-    "elementary_mathematics",
-    "formal_logic",
-    "global_facts",
-    "high_school_biology",
-    "high_school_chemistry",
-    "high_school_computer_science",
-    "high_school_european_history",
-    "high_school_geography",
-    "high_school_government_and_politics",
-    "high_school_macroeconomics",
-    "high_school_mathematics",
-    "high_school_microeconomics",
-    "high_school_physics",
-    "high_school_psychology",
-    "high_school_statistics",
-    "high_school_us_history",
-    "high_school_world_history",
-    "human_aging",
-    "human_sexuality",
-    "international_law",
-    "jurisprudence",
-    "logical_fallacies",
-    "machine_learning",
-    "management",
-    "marketing",
-    "medical_genetics",
-    "miscellaneous",
-    "moral_disputes",
-    "moral_scenarios",
-    "nutrition",
-    "philosophy",
-    "prehistory",
-    "professional_accounting",
-    "professional_law",
-    "professional_medicine",
-    "professional_psychology",
-    "public_relations",
-    "security_studies",
-    "sociology",
-    "us_foreign_policy",
-    "virology",
-    "world_religions",
-]
-
-
-def _download_and_extract(url: str, data_dir: str):
-    tar_path = os.path.join(data_dir, "data.tar")
-    os.makedirs(data_dir, exist_ok=True)
-    print(f"Downloading MMLU data from {url}...")
-    resp = requests.get(url, stream=True, timeout=300)
-    resp.raise_for_status()
-    total = int(resp.headers.get("content-length", 0))
-    with tqdm.tqdm(total=total, unit="B", unit_scale=True, desc="  Download") as bar:
-        with open(tar_path, "wb") as f:
-            for chunk in resp.iter_content(chunk_size=8192):
-                f.write(chunk)
-                bar.update(len(chunk))
-    print("Extracting...")
-    with tarfile.open(tar_path, "r") as tf:
-        tf.extractall(data_dir)
-    os.remove(tar_path)
-
-
-def download_mmlu(data_dir: str):
-    _download_and_extract(MMLU_URL, data_dir)
-    src = os.path.join(data_dir, "data")
-    if os.path.exists(src):
-        for item in os.listdir(src):
-            src_item = os.path.join(src, item)
-            dst_item = os.path.join(data_dir, item)
-            if os.path.exists(dst_item):
-                if os.path.isdir(dst_item):
-                    shutil.rmtree(dst_item)
-                else:
-                    os.remove(dst_item)
-            os.rename(src_item, dst_item)
-        os.rmdir(src)
-    print(f"MMLU data saved to {data_dir}")
-
-
-def _strip_prefix(text: str, prefix: str) -> str:
-    if text.startswith(prefix):
-        return text[len(prefix) :].strip()
-    return text
-
-
-def load_csv(path: str) -> list[dict]:
-    data = []
-    with open(path, "r", encoding="utf-8") as f:
-        for row in csv.reader(f):
-            if len(row) < 6:
-                continue
-            if row[0].strip().lower() == "question":
-                continue
-            data.append(
-                {
-                    "question": row[0].strip(),
-                    "A": _strip_prefix(row[1].strip(), "A)"),
-                    "B": _strip_prefix(row[2].strip(), "B)"),
-                    "C": _strip_prefix(row[3].strip(), "C)"),
-                    "D": _strip_prefix(row[4].strip(), "D)"),
-                    "answer": row[5].strip(),
-                }
-            )
-    return data
-
-
-def build_prompt(
-    question: str, choices: dict, subject: str, n_shot: int, dev_data: list[dict]
-) -> str:
-    prompt = ""
-    if n_shot > 0 and dev_data:
-        prompt = f"The following are multiple choice questions (with answers) about {subject}.\n\n"
-        for item in dev_data[:n_shot]:
-            prompt += f"Question: {item['question']}\n"
-            for k in ("A", "B", "C", "D"):
-                prompt += f"{k}. {item[k]}\n"
-            prompt += f"Answer: {item['answer']}\n\n"
-    prompt += f"Question: {question}\n"
-    for k in ("A", "B", "C", "D"):
-        prompt += f"{k}. {choices[k]}\n"
-    prompt += "Answer:"
-    return prompt
-
-
-def apply_chat(
-    tokenizer, raw_prompt: str, n_shot: int, dev_data: list[dict] | None
-) -> str:
-    """Wrap raw MMLU prompt in the model's chat template format.
-
-    For few-shot, prepend example Q&A pairs as a second user/assistant exchange.
-    """
-    messages = []
-    if n_shot > 0 and dev_data:
-        for item in dev_data[:n_shot]:
-            q = f"Question: {item['question']}\n"
-            for k in ("A", "B", "C", "D"):
-                q += f"{k}. {item[k]}\n"
-            q += "Answer:"
-            messages.append({"role": "user", "content": q})
-            messages.append({"role": "assistant", "content": item["answer"]})
-    messages.append({"role": "user", "content": raw_prompt})
-    return tokenizer.apply_chat_template(
-        messages, tokenize=False, add_generation_prompt=True
-    )
-
-
-def choice_logprob(
-    model, tokenizer, context_ids: list[int], choice_letter: str, device: str
-) -> float:
-    choice_text = choice_letter
-    choice_ids = tokenizer.encode(choice_text, add_special_tokens=False)
-    input_ids = context_ids + choice_ids
-    max_len = model.config.max_len
-    if len(input_ids) > max_len:
-        overflow = len(input_ids) - max_len
-        input_ids = input_ids[overflow:]
-        ctx_len = len(input_ids) - len(choice_ids)
-    else:
-        ctx_len = len(context_ids)
-
-    input_tensor = torch.tensor([input_ids], device=device, dtype=torch.long)
-    with torch.inference_mode():
-        logits = model(input_tensor)["logits"][0]
-
-    score = 0.0
-    for i, tid in enumerate(choice_ids):
-        pos = ctx_len - 1 + i
-        if pos >= len(logits):
-            break
-        score += F.log_softmax(logits[pos], dim=-1)[tid].item()
-    return score
-
-
-def evaluate_subject(
-    model,
-    tokenizer,
-    subject: str,
-    test_data: list[dict],
-    dev_data: list[dict] | None,
-    device: str,
-    n_shot: int,
-) -> tuple[float, int, int]:
-    correct = 0
-    total = 0
-    for item in tqdm.tqdm(test_data, desc=f"{subject:40s}", leave=False):
-        raw_prompt = build_prompt(
-            item["question"], item, subject, n_shot, dev_data or []
-        )
-        context = apply_chat(tokenizer, raw_prompt, n_shot, dev_data or [])
-        context_ids = tokenizer.encode(context)
-        scores = {
-            c: choice_logprob(model, tokenizer, context_ids, c, device)
-            for c in ("A", "B", "C", "D")
-        }
-        if max(scores, key=scores.get) == item["answer"]:
-            correct += 1
-        total += 1
-    return correct / total, correct, total
-
-
-def main():
-    parser = argparse.ArgumentParser(description="MMLU evaluation")
-    parser.add_argument(
-        "--param_path", type=str, default="./params", help="Model directory"
-    )
-    parser.add_argument(
-        "--data_dir", type=str, default="./mmlu_data", help="MMLU data directory"
-    )
-    parser.add_argument("--download", action="store_true", help="Download MMLU data")
-    parser.add_argument(
-        "--n_shot", type=int, default=5, help="Few-shot examples (0 for zero-shot)"
-    )
-    parser.add_argument(
-        "--subjects", type=str, nargs="+", help="Specific subjects (default: all)"
-    )
-    parser.add_argument("--output", type=str, help="Output JSON path")
-    parser.add_argument("--split", type=str, default="test", choices=["test", "val"])
-    parser.add_argument(
-        "--device",
-        type=str,
-        default="cuda" if torch.cuda.is_available() else "cpu",
-        help="Device",
-    )
-    parser.add_argument(
-        "--dtype",
-        type=str,
-        default="bfloat16" if torch.cuda.is_available() else "float32",
-        help="Torch dtype",
-    )
-    args = parser.parse_args()
-
-    if args.download or not os.path.exists(args.data_dir):
-        download_mmlu(args.data_dir)
-
-    model = AutoModel.from_pretrained(args.param_path)
-    tokenizer = AutoTokenizer.from_pretrained(args.param_path)
-    device = args.device
-    dtype = getattr(torch, args.dtype)
-    model.to(device=device, dtype=dtype)
-    model.eval()
-
-    subjects = args.subjects or MMLU_SUBJECTS
-    results = {}
-    total_correct = 0
-    total_questions = 0
-
-    for subject in subjects:
-        dev_path = os.path.join(args.data_dir, "dev", f"{subject}_dev.csv")
-        test_path = os.path.join(
-            args.data_dir, args.split, f"{subject}_{args.split}.csv"
-        )
-
-        if not os.path.exists(test_path):
-            print(f"  Skipping {subject}: test file not found")
-            continue
-
-        dev_data = load_csv(dev_path) if os.path.exists(dev_path) else None
-        test_data = load_csv(test_path)
-
-        acc, corr, tot = evaluate_subject(
-            model, tokenizer, subject, test_data, dev_data, device, args.n_shot
-        )
-        results[subject] = {"accuracy": round(acc, 4), "correct": corr, "total": tot}
-        total_correct += corr
-        total_questions += tot
-        print(f"  {subject:40s}  {acc:.2%}  ({corr}/{tot})")
-
-    overall = total_correct / total_questions if total_questions else 0
-    print(f"\n{'=' * 70}")
-    print(f"  Overall: {overall:.2%}  ({total_correct}/{total_questions})")
-    results["_overall"] = {
-        "accuracy": round(overall, 4),
-        "correct": total_correct,
-        "total": total_questions,
-    }
-
-    if args.output:
-        with open(args.output, "w", encoding="utf-8") as f:
-            json.dump(results, f, indent=2)
-        print(f"Results saved to {args.output}")
-
-
-if __name__ == "__main__":
-    main()
@@ -1,153 +0,0 @@
-"""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()
@@ -1,6 +1,5 @@
 import argparse
 import json
-from typing import Optional

 import torch

@@ -18,7 +17,7 @@ def processor(
    top_p: float,
    question_key: str,
    response_key: str,
-    max_tokens: Optional[int],
+    max_tokens: int,
    batch_size: int,
 ):
    # Load model and tokenizer
@@ -73,7 +72,7 @@ def processor(


 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Batch generation from JSONL file.")
+    parser = argparse.ArgumentParser(description="Run generate with a Khaosz model.")

    parser.add_argument(
        "--param_path", type=str, required=True, help="Path to the model directory."
@@ -94,42 +93,36 @@ if __name__ == "__main__":
        "--question_key",
        type=str,
        default="question",
-        help="Key for the question in the input JSON (default: question).",
+        help="Key for the question in the input JSON.",
    )
    parser.add_argument(
        "--response_key",
        type=str,
        default="response",
-        help="Key for the response in the output JSON (default: response).",
+        help="Key for the response in the output JSON.",
    )
    parser.add_argument(
        "--temperature",
        type=float,
        default=0.60,
-        help="Temperature for generating responses (default: 0.60).",
+        help="Temperature for generating responses.",
    )
    parser.add_argument(
-        "--top_k",
-        type=int,
-        default=30,
-        help="Top-k value for generating responses (default: 30).",
+        "--top_k", type=int, default=30, help="Top-k value for generating responses."
    )
    parser.add_argument(
        "--top_p",
        type=float,
        default=0.95,
-        help="Top-p value for generating responses (default: 0.95).",
+        help="Top-p value for generating responses.",
    )
    parser.add_argument(
-        "--batch_size",
-        type=int,
-        default=1,
-        help="Batch size for generating responses (default: 1).",
+        "--batch_size", type=int, default=1, help="Batch size for generating responses."
    )
    parser.add_argument(
        "--max_tokens",
        type=int,
-        default=None,
+        default=2048,
        help="Maximum tokens to generate (default: model config max_len).",
    )

@@ -10,11 +10,11 @@ from astrai.tokenize import AutoTokenizer


 def process_file(
-    param_path: str, input_file: str, output_file: str, batch_size: int, text_key: str
+    model_dir: str, input_file: str, output_file: str, batch_size: int, text_key: str
 ):
    # Load model and tokenizer
-    model = AutoModel.from_pretrained(param_path)
-    tokenizer = AutoTokenizer.from_pretrained(param_path)
+    model = AutoModel.from_pretrained(model_dir)
+    tokenizer = AutoTokenizer.from_pretrained(model_dir)
    model.to(device="cuda", dtype=torch.bfloat16)

    with open(input_file, "r", encoding="utf-8") as f:
@@ -44,8 +44,8 @@ def process_file(

        for seq in batch_encoded:
            pad_len = max_len - len(seq)
-            padded_seq = seq + [tokenizer.pad_id] * pad_len
-            mask = [True] * len(seq) + [False] * pad_len
+            padded_seq = [tokenizer.pad_id] * pad_len + seq
+            mask = [False] * pad_len + [True] * len(seq)
            padded_ids.append(padded_seq)
            masks.append(mask)

@@ -86,9 +86,9 @@ def process_file(


 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Perplexity evaluation on JSONL text.")
+    parser = argparse.ArgumentParser(description="Run perplexity with a Khaosz model.")
    parser.add_argument(
-        "--param_path", type=str, required=True, help="Path to the model directory."
+        "--model_dir", type=str, required=True, help="Path to the model directory."
    )
    parser.add_argument(
        "--input_file", type=str, required=True, help="Path to the input file."
@@ -1,38 +0,0 @@
-"""CLI: JSONL → tokenized .h5/.bin via config-driven Pipeline."""
-
-import argparse
-
-from astrai.config.preprocess_config import PipelineConfig
-from astrai.preprocessing.pipeline import Pipeline
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Raw JSONL → tokenized .h5/.bin via config-driven Pipeline"
-    )
-    parser.add_argument(
-        "inputs", nargs="+", metavar="JSONL", help="One or more JSONL files"
-    )
-    parser.add_argument("--output_dir", "-o", required=True, help="Output directory")
-    parser.add_argument(
-        "--config", "-c", required=True, help="Path to pipeline config JSON"
-    )
-    parser.add_argument(
-        "--tokenizer_path",
-        default="params",
-        help="Path to tokenizer directory (default: params)",
-    )
-    args = parser.parse_args()
-
-    config = PipelineConfig.from_file(args.config)
-
-    Pipeline(
-        config=config,
-        input_paths=args.inputs,
-        output_dir=args.output_dir,
-        tokenizer_path=args.tokenizer_path,
-    ).run()
-
-
-if __name__ == "__main__":
-    main()
@@ -18,7 +18,7 @@ def main():
        "--reload", action="store_true", help="Enable auto-reload for development"
    )
    parser.add_argument(
-        "--param_path",
+        "--param-path",
        type=Path,
        default=None,
        help="Path to model parameters (default: project_root/params)",
@@ -2,13 +2,16 @@ import argparse
 import os
 from functools import partial

+import safetensors.torch as st
 import torch
+import torch.nn as nn
 import torch.optim as optim
+from torch.nn.parallel import DistributedDataParallel as DDP

 from astrai.config import AutoRegressiveLMConfig, TrainConfig
 from astrai.dataset import DatasetFactory
 from astrai.model import AutoRegressiveLM
-from astrai.model.components.decoder_block import DecoderBlock
+from astrai.parallel import get_rank
 from astrai.trainer import SchedulerFactory, Trainer


@@ -113,15 +116,9 @@ def parse_args() -> argparse.Namespace:
    parser.add_argument(
        "--label_smoothing",
        type=float,
-        default=0.0,
+        default=0.05,
        help="cross_entropy function label smoothing parameter",
    )
-    parser.add_argument(
-        "--gradient_checkpointing",
-        action=argparse.BooleanOptionalAction,
-        default=False,
-        help="Enable activation checkpointing for DecoderBlock modules.",
-    )

    parser.add_argument(
        "--ckpt_interval",
@@ -135,30 +132,6 @@ def parse_args() -> argparse.Namespace:
        default="checkpoint",
        help="Directory to save checkpoints.",
    )
-    parser.add_argument(
-        "--val_split",
-        type=float,
-        default=None,
-        help="Ratio to split from training dataset for validation (e.g. 0.05).",
-    )
-    parser.add_argument(
-        "--val_step",
-        type=int,
-        default=1000,
-        help="Number of optimizer steps between validation runs.",
-    )
-    parser.add_argument(
-        "--metrics",
-        nargs="*",
-        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",
-        type=str,
-        default="checkpoint/logs",
-        help="Directory for metric logs.",
-    )
    parser.add_argument(
        "--grpo_sync_interval",
        type=int,
@@ -169,38 +142,10 @@ def parse_args() -> argparse.Namespace:
        "--start_epoch", type=int, default=0, help="Start epoch for training."
    )
    parser.add_argument(
-        "--start_samples",
-        type=int,
-        default=0,
-        help="Start samples (per rank) for training.",
+        "--start_batch", type=int, default=0, help="Start batch for training."
    )

-    parser.add_argument(
-        "--master_addr",
-        type=str,
-        default="localhost",
-        help="Master node address for distributed training.",
-    )
-    parser.add_argument(
-        "--master_port",
-        type=str,
-        default="29500",
-        help="Master node port for distributed training.",
-    )
-    parser.add_argument(
-        "--backend",
-        type=str,
-        default="nccl",
-        help="Distributed training backend.",
-    )
    parser.add_argument("--nprocs", type=int, default=1, help="Number of GPUs to use.")
-    parser.add_argument(
-        "--parallel_mode",
-        type=str,
-        default="none",
-        choices=["none", "ddp", "fsdp"],
-        help="Parallel training strategy (none, ddp, fsdp).",
-    )
    parser.add_argument(
        "--device_type", type=str, default="cuda", help="Device type to use."
    )
@@ -211,82 +156,40 @@ def parse_args() -> argparse.Namespace:
        choices=["spawn", "fork", "forkserver"],
        help="Multiprocessing start method.",
    )
-    parser.add_argument(
-        "--neftune_alpha",
-        type=float,
-        default=0.0,
-        help="NEFTune noise alpha (0=disabled, typical: 5.0).",
-    )
-
-    parser.add_argument(
-        "--schedule_type",
-        type=str,
-        default="cosine",
-        choices=["cosine", "sgdr", "wsd"],
-        help="Learning rate scheduler type.",
-    )
-    parser.add_argument(
-        "--min_rate",
-        type=float,
-        default=None,
-        help="Minimum LR as fraction of base LR. Uses scheduler default if not set (cosine/sgdr: 0.05, wsd: 0.0).",
-    )
-    parser.add_argument(
-        "--cycle_length",
-        type=int,
-        default=None,
-        help="SGDR first cycle length in steps. Defaults to total_steps - warmup_steps.",
-    )
-    parser.add_argument(
-        "--t_mult",
-        type=int,
-        default=2,
-        help="SGDR cycle length multiplier per restart.",
-    )
-    parser.add_argument(
-        "--stable_steps",
-        type=int,
-        default=None,
-        help="WSD stable plateau steps. Required when --schedule_type wsd.",
-    )
-    parser.add_argument(
-        "--decay_steps",
-        type=int,
-        default=None,
-        help="WSD decay steps. Defaults to total_steps - warmup_steps - stable_steps.",
-    )

    args = parser.parse_args()

    return args


-def create_model(config):
-    return AutoRegressiveLM(config).to(dtype=torch.bfloat16)
+def ddp_wrap(model: nn.Module):
+    local_rank = get_rank()
+    ddp_model = DDP(
+        model,
+        device_ids=[local_rank],
+        output_device=local_rank,
+        static_graph=True,
+        find_unused_parameters=False,
+        gradient_as_bucket_view=True,
+        broadcast_buffers=False,
+    )
+    return ddp_model


-def create_optimizer(model, **kwargs) -> optim.Optimizer:
-    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_optimizer(model: nn.Module, **kwargs) -> optim.Optimizer:
+    return optim.AdamW(model.parameters(), fused=True, **kwargs)


 def create_scheduler(
    optimizer: optim.Optimizer, **kwargs
 ) -> optim.lr_scheduler.LRScheduler:
-    schedule_type = kwargs.pop("schedule_type")
-    return SchedulerFactory.create(schedule_type, optimizer, **kwargs)
+    return SchedulerFactory.create(optimizer, **kwargs)
+
+
+def prepare_checkpoint(model: nn.Module) -> dict:
+    if isinstance(model, DDP):
+        return model.module.state_dict()
+    return model.state_dict()


 def compute_total_steps(
@@ -314,15 +217,11 @@ def train(
    n_epoch: int,
    batch_per_device: int,
    start_epoch: int,
-    start_samples: int,
+    start_batch: int,
    grad_accum_steps: int,
    warmup_ratio: float,
    ckpt_interval: int,
    ckpt_dir: str,
-    val_split: float,
-    val_step: int,
-    metrics: list[str],
-    log_dir: str,
    dpo_beta: float,
    grpo_clip_eps: float,
    grpo_kl_coef: float,
@@ -336,37 +235,33 @@ def train(
    random_seed: int,
    num_workers: int,
    pin_memory: bool,
-    gradient_checkpointing: bool,
    window_size: int,
    stride: int,
    nprocs: int,
-    parallel_mode: str,
    device_type: str,
-    backend: str,
-    master_addr: str,
-    master_port: str,
    start_method: str,
-    neftune_alpha: float,
-    schedule_type: str,
-    min_rate: float,
-    cycle_length: int,
-    t_mult: int,
-    stable_steps: int,
-    decay_steps: int,
 ):
    assert train_type in ["seq", "sft", "dpo", "grpo"]
    assert os.path.exists(param_path)
-    if nprocs > 1 and parallel_mode == "none":
-        raise ValueError("--nprocs > 1 requires --parallel_mode to be 'ddp' or 'fsdp'")

    # Load config
    config_path = os.path.join(param_path, "config.json")
    config = AutoRegressiveLMConfig.from_file(config_path)
-    config.neftune_alpha = neftune_alpha

    if window_size is None:
        window_size = config.max_len

+    # Create bare AutoRegressiveLM (for training, no tokenizer needed)
+    model = AutoRegressiveLM(config)
+
+    # Load weights if available
+    weights_path = os.path.join(param_path, "model.safetensors")
+    if os.path.exists(weights_path):
+        state_dict = st.load_file(weights_path)
+        model.load_state_dict(state_dict, strict=False)
+
+    model = model.to(dtype=torch.bfloat16)
+
    strategy_kwargs = {
        "beta": dpo_beta,
        "label_smoothing": label_smoothing,
@@ -376,12 +271,6 @@ def train(
        "sync_interval": grpo_sync_interval,
    }

-    executor_kwargs = {
-        "gradient_as_bucket_view": True,
-        "broadcast_buffers": False,
-    }
-
-    model_fn = partial(create_model, config)
    dataset = DatasetFactory.load(
        train_type=train_type,
        load_path=data_root_path,
@@ -402,36 +291,18 @@ def train(
        len(dataset), n_epoch, batch_per_device, nprocs, grad_accum_steps
    )
    warmup_steps = int(warmup_ratio * total_steps)
-    warmup_steps = min(warmup_steps, total_steps)
-
-    scheduler_kwargs = {"warmup_steps": warmup_steps}
-
-    if schedule_type == "cosine":
-        scheduler_kwargs["lr_decay_steps"] = total_steps - warmup_steps
-    elif schedule_type == "sgdr":
-        scheduler_kwargs["cycle_length"] = cycle_length or (total_steps - warmup_steps)
-        scheduler_kwargs["t_mult"] = t_mult
-    elif schedule_type == "wsd":
-        remaining = total_steps - warmup_steps
-        stable_steps_ = stable_steps or max(1, int(remaining * 0.8))
-        scheduler_kwargs["stable_steps"] = stable_steps_
-        scheduler_kwargs["decay_steps"] = max(
-            1, decay_steps or (remaining - stable_steps_)
-        )
-
-    if min_rate is not None:
-        scheduler_kwargs["min_rate"] = min_rate

    scheduler_fn = partial(
        create_scheduler,
-        schedule_type=schedule_type,
-        **scheduler_kwargs,
+        **{
+            "schedule_type": "cosine",
+            "warmup_steps": min(warmup_steps, total_steps),
+            "lr_decay_steps": total_steps - min(warmup_steps, total_steps),
+        },
    )

-    grad_ckpt_modules = [DecoderBlock] if gradient_checkpointing else []
-
    train_config = TrainConfig(
-        model_fn=model_fn,
+        model=model,
        strategy=train_type,
        dataset=dataset,
        optimizer_fn=optimizer_fn,
@@ -440,7 +311,7 @@ def train(
        n_epoch=n_epoch,
        batch_per_device=batch_per_device,
        start_epoch=start_epoch,
-        start_samples=start_samples,
+        start_batch=start_batch,
        ckpt_interval=ckpt_interval,
        grad_accum_steps=grad_accum_steps,
        max_grad_norm=max_grad_norm,
@@ -448,24 +319,15 @@ def train(
        num_workers=num_workers,
        pin_memory=pin_memory,
        nprocs=nprocs,
-        backend=backend,
-        master_addr=master_addr,
-        master_port=master_port,
-        parallel_mode=parallel_mode,
+        parallel_wrapper=ddp_wrap,
+        state_dict_fn=prepare_checkpoint,
        device_type=device_type,
        start_method=start_method,
-        val_split=val_split,
-        val_step=val_step,
-        metrics=metrics,
-        log_dir=log_dir,
-        gradient_checkpointing_modules=grad_ckpt_modules,
-        executor_kwargs=executor_kwargs,
        extra_kwargs=strategy_kwargs,
-        neftune_alpha=neftune_alpha,
    )

    trainer = Trainer(train_config)
-    trainer.train(resume_dir=param_path)
+    trainer.train()


 if __name__ == "__main__":
@@ -75,7 +75,7 @@ class MultiTurnDataset(Dataset):


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

    def __init__(self, length=10, stop_after=5):
        self.length = length
@@ -1,235 +0,0 @@
-import json
-import os
-import tempfile
-
-import pytest
-from tokenizers import Tokenizer, models, pre_tokenizers, trainers
-
-from astrai.config.preprocess_config import (
-    InputConfig,
-    PipelineConfig,
-    ProcessingConfig,
-)
-from astrai.preprocessing.builder import SectionedMaskBuilder
-from astrai.tokenize import AutoTokenizer
-
-_SPECIAL_TOKENS_CONFIG = {
-    "bos_token": "<|begin_of_sentence|>",
-    "eos_token": "<|end_of_sentence|>",
-    "pad_token": "<|_pad_|>",
-    "unk_token": "<|_unk_|>",
-    "im_start": "<|im_start|>",
-    "im_end": "<|im_end|>",
-}
-
-_SPECIAL_TOKENS = list(_SPECIAL_TOKENS_CONFIG.values())
-
-_CHAT_TEMPLATE = (
-    "{% for message in messages %}"
-    "{% if message['role'] == 'system' %}"
-    "<|im_start|>system\n{{ message['content'] }}<|im_end|>\n"
-    "{% elif message['role'] == 'user' %}"
-    "<|im_start|>user\n{{ message['content'] }}<|im_end|>\n"
-    "{% elif message['role'] == 'assistant' %}"
-    "<|im_start|>assistant\n{{ message['content'] }}<|im_end|>\n"
-    "{% endif %}"
-    "{% endfor %}"
-    "{% if add_generation_prompt %}<|im_start|>assistant\n{% endif %}"
-)
-
-_CHAT_SECTIONS = [{"field": "messages", "action": "$role", "template": True}]
-
-_INSTRUCTION_SECTIONS = [
-    {"field": "prompt", "action": "mask", "add_special_tokens": True},
-    {"field": "response", "action": "train"},
-]
-
-_TEXT_SECTIONS = [{"field": "text", "action": "train"}]
-
-_GRPO_RESPONSE_SECTIONS = [{"field": "responses", "action": "train"}]
-
-
-def _build_chat_tokenizer():
-    tok = Tokenizer(models.BPE())
-    tok.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=False)
-    tr = trainers.BpeTrainer(
-        vocab_size=512,
-        min_frequency=1,
-        special_tokens=_SPECIAL_TOKENS,
-    )
-    train_data = [
-        "hello world",
-        "Hi there!",
-        "You are helpful.",
-        "What is 2+2?",
-        "Tell me a story about dragons and knights.",
-        "Sure, here is a tale.",
-        "Translate to French: Hello",
-        "Bonjour",
-        "Artificial Intelligence is a field of computer science.",
-        "system",
-        "user",
-        "assistant",
-        "<|im_start|>",
-        "<|im_end|>",
-        *[chr(i) for i in range(32, 127)],
-    ]
-    tok.train_from_iterator(train_data, tr)
-
-    auto_tok = AutoTokenizer()
-    auto_tok._tokenizer = tok
-    auto_tok._special_token_map = {
-        "bos_token": "<|begin_of_sentence|>",
-        "eos_token": "<|end_of_sentence|>",
-        "pad_token": "<|_pad_|>",
-        "unk_token": "<|_unk_|>",
-    }
-    auto_tok.set_chat_template(_CHAT_TEMPLATE)
-    return auto_tok
-
-
-@pytest.fixture(scope="session")
-def chat_tokenizer():
-    return _build_chat_tokenizer()
-
-
-@pytest.fixture
-def temp_dir():
-    d = tempfile.mkdtemp()
-    yield d
-    import shutil
-
-    shutil.rmtree(d, ignore_errors=True)
-
-
-def make_chat_config():
-    return PipelineConfig(
-        input=InputConfig(sections=_CHAT_SECTIONS),
-        mask={"system": "mask", "user": "mask", "assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-
-
-def make_instruction_config():
-    return PipelineConfig(
-        input=InputConfig(sections=_INSTRUCTION_SECTIONS),
-        mask={"prompt": "mask", "response": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-
-
-def make_text_config():
-    return PipelineConfig(
-        input=InputConfig(sections=_TEXT_SECTIONS),
-        preprocessing=ProcessingConfig(
-            max_seq_len=2048, min_chars=1, max_chars=2_000_000
-        ),
-    )
-
-
-def make_dpo_chat_config():
-    return PipelineConfig(
-        input=InputConfig(
-            sources={
-                "chosen": {
-                    "sections": [
-                        {"field": "chosen", "action": "$role", "template": True}
-                    ]
-                },
-                "rejected": {
-                    "sections": [
-                        {"field": "rejected", "action": "$role", "template": True}
-                    ]
-                },
-            }
-        ),
-        mask={"user": "mask", "assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-
-
-def make_grpo_config():
-    return PipelineConfig(
-        input=InputConfig(
-            sources={
-                "prompts": {
-                    "sections": [
-                        {"field": "prompt", "action": "mask", "template": True}
-                    ]
-                },
-                "responses": {
-                    "sections": _GRPO_RESPONSE_SECTIONS,
-                    "list_field": True,
-                    "mask_key": "masks",
-                },
-                "rewards": {
-                    "sections": [{"field": "rewards", "action": "value"}],
-                },
-            }
-        ),
-        mask={"user": "mask", "assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-
-
-def make_grpo_no_template_config():
-    return PipelineConfig(
-        input=InputConfig(
-            sources={
-                "prompts": {
-                    "sections": [
-                        {
-                            "field": "prompt",
-                            "action": "mask",
-                            "add_special_tokens": True,
-                        }
-                    ]
-                },
-                "responses": {
-                    "sections": _GRPO_RESPONSE_SECTIONS,
-                    "list_field": True,
-                    "mask_key": "masks",
-                },
-                "rewards": {
-                    "sections": [{"field": "rewards", "action": "value"}],
-                },
-            }
-        ),
-        mask={"user": "mask", "assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-
-
-@pytest.fixture
-def builder():
-    return SectionedMaskBuilder()
-
-
-@pytest.fixture
-def tokenizer_dir(temp_dir, test_tokenizer):
-    d = os.path.join(temp_dir, "tok")
-    os.makedirs(d, exist_ok=True)
-    test_tokenizer._tokenizer.save(os.path.join(d, "tokenizer.json"))
-    with open(os.path.join(d, "tokenizer_config.json"), "w") as f:
-        json.dump(
-            {"special_tokens": {"pad_token": "<|_pad_|>", "unk_token": "<|_unk_|>"}}, f
-        )
-    return d
-
-
-@pytest.fixture
-def chat_tokenizer_dir(temp_dir, chat_tokenizer):
-    d = os.path.join(temp_dir, "tok")
-    os.makedirs(d, exist_ok=True)
-    chat_tokenizer._tokenizer.save(os.path.join(d, "tokenizer.json"))
-    with open(os.path.join(d, "tokenizer_config.json"), "w") as f:
-        json.dump(
-            {"special_tokens": _SPECIAL_TOKENS_CONFIG, "chat_template": _CHAT_TEMPLATE},
-            f,
-        )
-    return d
@@ -1,4 +1,3 @@
-import os
 import tempfile

 import torch
@@ -25,9 +24,7 @@ def test_single_process():

        scheduler.step()

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

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

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


 def test_checkpoint_with_extra():
+    """Verify extra keys are saved as individual .pt files and loaded back."""
    model = torch.nn.Linear(10, 5)
    optimizer = AdamW(model.parameters(), lr=1e-3)
    optimizer.step()
@@ -48,15 +46,14 @@ def test_checkpoint_with_extra():
        "scheduler": {"last_epoch": 5},
    }
    checkpoint = Checkpoint(
-        state_dict=model.state_dict(),
-        epoch=1,
-        consumed_samples=40,
-        extra=extra,
+        state_dict=model.state_dict(), epoch=1, iteration=10, extra=extra
    )

    with tempfile.TemporaryDirectory() as tmpdir:
        checkpoint.save(tmpdir)

+        import os
+
        assert os.path.exists(os.path.join(tmpdir, "optimizer.pt"))
        assert os.path.exists(os.path.join(tmpdir, "scheduler.pt"))

@@ -82,7 +79,7 @@ def simple_training():
    checkpoint = Checkpoint(
        state_dict=model.state_dict(),
        epoch=2,
-        consumed_samples=40,
+        iteration=10,
    )

    rank = get_rank()
@@ -5,81 +5,40 @@ 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,
+    BaseSegmentFetcher,
+    H5Storage,
+    MultiSegmentFetcher,
+    StorageFactory,
    detect_format,
-)
-from astrai.serialization import (
-    load_bin,
-    save_bin,
+    load_json,
    save_h5,
 )


-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
-):
-    if data is None:
-        data = {"sequence": [_rand_seq(seq_length)]}
-    save_h5(test_dir, name, data)
-    return DatasetFactory.load(
-        train_type,
-        test_dir,
-        window_size=load_kwargs.pop("window_size", 64),
-        **load_kwargs,
-    )
-
-
 def test_dataset_loader_random_paths(base_test_env):
    """Test dataset loader with multiple random paths"""
    test_dir = base_test_env["test_dir"]

+    # Create multiple mmap dataset directories with random data
    num_files = np.random.randint(2, 5)
+
    for i in range(num_files):
        seq_length = np.random.randint(200, 400)
-        dummy_data = {"sequence": [_rand_seq(seq_length) for _ in range(10)]}
-        loaded_dataset = _make_seq_dataset(
-            test_dir, f"data_{i}", seq_length, data=dummy_data
+        dummy_data = {
+            "sequence": [
+                torch.randint(0, 1000, (seq_length,), dtype=torch.int64)
+                for _ in range(10)
+            ],
+        }
+        save_h5(test_dir, f"data_{i}", dummy_data)
+
+        # Test loading with multiple paths
+        loaded_dataset = DatasetFactory.load(
+            train_type="seq",
+            load_path=test_dir,
+            window_size=64,
        )
        assert loaded_dataset is not None
        assert len(loaded_dataset) > 0
@@ -97,15 +56,23 @@ def test_dpo_strategy_with_random_data(base_test_env):
    """Test DPO strategy with randomized preference data"""
    test_dir = base_test_env["test_dir"]

+    # Create DPO-style data with memory mapping format
    seq_length = np.random.randint(100, 200)
+
    dummy_data = {
-        "chosen": [_rand_seq(seq_length)],
-        "rejected": [_rand_seq(seq_length)],
+        "chosen": [torch.randint(0, 1000, (seq_length,), dtype=torch.int64)],
+        "rejected": [torch.randint(0, 1000, (seq_length,), dtype=torch.int64)],
        "chosen_mask": [torch.ones(seq_length, dtype=torch.bool)],
        "rejected_mask": [torch.ones(seq_length, dtype=torch.bool)],
    }
-    dpo_dataset = _make_seq_dataset(
-        test_dir, "dpo_data", seq_length, train_type="dpo", data=dummy_data
+
+    save_h5(test_dir, "dpo_data", dummy_data)
+
+    # Load DPO dataset
+    dpo_dataset = DatasetFactory.load(
+        train_type="dpo",
+        load_path=test_dir,
+        window_size=64,
    )

    assert dpo_dataset is not None
@@ -127,14 +94,21 @@ def test_sft_dataset_with_random_data(base_test_env):
    """Test SFT dataset with random data"""
    test_dir = base_test_env["test_dir"]

+    # Create SFT-style data with memory mapping format
    seq_length = np.random.randint(100, 200)
+
    dummy_data = {
-        "sequence": [_rand_seq(seq_length)],
+        "sequence": [torch.randint(0, 1000, (seq_length,), dtype=torch.int64)],
        "loss_mask": [torch.ones(seq_length, dtype=torch.bool)],
-        "position_ids": [torch.arange(seq_length, dtype=torch.int32)],
    }
-    sft_dataset = _make_seq_dataset(
-        test_dir, "sft_data", seq_length, train_type="sft", data=dummy_data
+
+    save_h5(test_dir, "sft_data", dummy_data)
+
+    # Load SFT dataset
+    sft_dataset = DatasetFactory.load(
+        train_type="sft",
+        load_path=test_dir,
+        window_size=64,
    )

    assert sft_dataset is not None
@@ -155,11 +129,25 @@ def test_dataset_with_custom_stride(base_test_env):
    """Test dataset with custom stride parameter"""
    test_dir = base_test_env["test_dir"]

+    # Create test data
+    seq_length = 200
+    dummy_data = {
+        "sequence": [torch.randint(0, 1000, (seq_length,), dtype=torch.int64)],
+    }
+
+    save_h5(test_dir, "stride_test_data", dummy_data)
+
+    # Test with custom stride
    custom_stride = 32
-    dataset = _make_seq_dataset(test_dir, "stride_test_data", stride=custom_stride)
+    dataset = DatasetFactory.load(
+        train_type="seq", load_path=test_dir, window_size=64, stride=custom_stride
+    )
+
    assert dataset is not None
    assert len(dataset) > 0

+    # With stride 32 and window 64 on 200 length data, we should get more samples
+    # than with default stride (which equals window size)
    default_stride_dataset = DatasetFactory.load(
        train_type="seq",
        load_path=test_dir,
@@ -169,12 +157,131 @@ def test_dataset_with_custom_stride(base_test_env):
    assert len(dataset) > len(default_stride_dataset)


-def test_dataset_count_property(base_test_env):
+# ============== JSON Storage Tests (raw text + tokenizer) ==============
+
+
+def _make_tokenizer_fn(tokenizer):
+    """Wrap tokenizer.encode() as a str -> List[int] callable."""
+    return lambda text: tokenizer.encode(text, add_special_tokens=False)
+
+
+def test_seq_dataset_from_json_text(base_test_env):
+    """Test loading SEQ dataset from raw-text JSON with tokenizer"""
+    tokenizer = base_test_env["tokenizer"]
+    tokenizer_fn = _make_tokenizer_fn(tokenizer)
    test_dir = base_test_env["test_dir"]
-    dataset = _make_seq_dataset(test_dir, "count_test_data")
-    assert dataset.count == 200
-    assert dataset.count > len(dataset)
-    assert len(dataset) == (200 - 1 - 64) // 64 + 1
+    data_dir = os.path.join(test_dir, "json_text")
+    os.makedirs(data_dir, exist_ok=True)
+
+    texts = [
+        "hello world this is a test sentence for tokenizer",
+        "another sentence with different words and tokens",
+        "machine learning is fascinating and powerful",
+    ]
+
+    json_path = os.path.join(data_dir, "seq_data.json")
+    with open(json_path, "w", encoding="utf-8") as f:
+        json.dump({"sequence": texts}, f, ensure_ascii=False)
+
+    dataset = DatasetFactory.load(
+        train_type="seq",
+        load_path=data_dir,
+        window_size=16,
+        tokenizer=tokenizer_fn,
+    )
+    assert dataset is not None
+    assert len(dataset) > 0
+    assert dataset.count > 0
+    assert "sequence" in dataset.keys
+
+    item = dataset[0]
+    assert "input_ids" in item
+    assert "target_ids" in item
+    assert item["input_ids"].shape[0] == 16
+
+
+def test_sft_dataset_from_json_text(base_test_env):
+    """Test loading SFT dataset from raw-text JSON with tokenizer"""
+    tokenizer = base_test_env["tokenizer"]
+    tokenizer_fn = _make_tokenizer_fn(tokenizer)
+    test_dir = base_test_env["test_dir"]
+    data_dir = os.path.join(test_dir, "json_sft")
+    os.makedirs(data_dir, exist_ok=True)
+
+    texts = [
+        "user asks a question about the weather",
+        "assistant provides a helpful response to the user",
+    ]
+
+    json_path = os.path.join(data_dir, "sft_data.json")
+    with open(json_path, "w", encoding="utf-8") as f:
+        json.dump(
+            {"sequence": texts, "loss_mask": texts},
+            f,
+            ensure_ascii=False,
+        )
+
+    dataset = DatasetFactory.load(
+        train_type="sft",
+        load_path=data_dir,
+        window_size=16,
+        tokenizer=tokenizer_fn,
+    )
+    assert dataset is not None
+    assert len(dataset) > 0
+
+    item = dataset[0]
+    assert "loss_mask" in item
+
+
+def test_json_storage_explicit_tokenizer(base_test_env):
+    """Test explicit JSON storage with tokenizer"""
+    tokenizer = base_test_env["tokenizer"]
+    tokenizer_fn = _make_tokenizer_fn(tokenizer)
+    test_dir = base_test_env["test_dir"]
+    data_dir = os.path.join(test_dir, "json_explicit")
+    os.makedirs(data_dir, exist_ok=True)
+
+    texts = ["abcdefghijklmnopqrstuvwxyz" * 10]
+
+    json_path = os.path.join(data_dir, "data.json")
+    with open(json_path, "w", encoding="utf-8") as f:
+        json.dump({"sequence": texts}, f, ensure_ascii=False)
+
+    token_count = len(tokenizer_fn(texts[0]))
+
+    dataset = DatasetFactory.load(
+        train_type="seq",
+        load_path=data_dir,
+        window_size=32,
+        storage_type="json",
+        tokenizer=tokenizer_fn,
+    )
+    assert dataset is not None
+    assert len(dataset) > 0
+    assert dataset.count == token_count
+
+
+def test_dataset_count_property(base_test_env):
+    """Test the count property returns correct raw token count"""
+    test_dir = base_test_env["test_dir"]
+
+    seq_length = 200
+    dummy_data = {
+        "sequence": [torch.randint(0, 1000, (seq_length,), dtype=torch.int64)],
+    }
+
+    save_h5(test_dir, "count_test_data", dummy_data)
+
+    dataset = DatasetFactory.load(
+        train_type="seq",
+        load_path=test_dir,
+        window_size=64,
+    )
+
+    assert dataset.count == seq_length
+    assert dataset.count > len(dataset)  # raw tokens > windows
+    assert len(dataset) == (seq_length - 1 - 64) // 64 + 1


 def test_empty_dataset_count():
@@ -185,10 +292,17 @@ def test_empty_dataset_count():


 def test_dataset_too_short_for_window(base_test_env):
+    """Dataset shorter than window_size returns __len__ == 0"""
    test_dir = base_test_env["test_dir"]
-    dataset = _make_seq_dataset(test_dir, "short", seq_length=30)
+    seq_length = 30
+    save_h5(
+        test_dir,
+        "short",
+        {"sequence": [torch.randint(0, 1000, (seq_length,), dtype=torch.int64)]},
+    )
+    dataset = DatasetFactory.load("seq", test_dir, window_size=64)
    assert len(dataset) == 0
-    assert dataset.count == 30
+    assert dataset.count == seq_length


 def test_unloaded_dataset_getitem_raises():
@@ -204,25 +318,37 @@ def test_unloaded_dataset_len():
    assert len(dataset) == 0


-def test_store_unloaded_len():
-    """Unloaded Store has __len__ == 0"""
-    store = H5Store()
-    assert len(store) == 0
-    assert store.keys == []
+def test_base_segment_fetcher_empty():
+    """BaseSegmentFetcher with empty segments list"""
+    fetcher = BaseSegmentFetcher([])
+    assert len(fetcher) == 0
+    with pytest.raises(ValueError, match="out of bounds"):
+        fetcher.fetch_data(0, 1)


-def test_store_fetch_begin_equals_end(base_test_env):
+def test_base_segment_fetcher_begin_equals_end(base_test_env):
+    """fetch_data with begin == end returns empty tensor"""
    test_dir = base_test_env["test_dir"]
-    dataset = _make_seq_dataset(test_dir, "empty_fetch", seq_length=100, window_size=32)
-    result = dataset.storage.fetch(10, 10, "sequence")
+    dummy = {"sequence": [torch.randint(0, 1000, (100,), dtype=torch.int64)]}
+    save_h5(test_dir, "empty_fetch", dummy)
+
+    dataset = DatasetFactory.load("seq", test_dir, window_size=32)
+    fetcher = dataset.storage._fetcher.multi_fetchers["sequence"]
+    result = fetcher.fetch_data(10, 10)
    assert result.numel() == 0


-def test_store_fetch_before_load():
-    """Store.fetch before load raises RuntimeError"""
-    store = H5Store()
+def test_multi_segment_fetcher_empty_dict():
+    """MultiSegmentFetcher with empty dict has __len__ == 0"""
+    fetcher = MultiSegmentFetcher({})
+    assert len(fetcher) == 0
+
+
+def test_storage_fetch_before_load():
+    """BaseStorage.fetch before load raises RuntimeError"""
+    storage = H5Storage()
    with pytest.raises(RuntimeError, match="not loaded"):
-        store.fetch(0, 10, "sequence")
+        storage.fetch(0, 10, "sequence")


 def test_detect_format_nonexistent_path():
@@ -241,274 +367,54 @@ def test_detect_format_unsupported_file(base_test_env):
        detect_format(path)


-def test_create_store_invalid_type():
-    """StoreFactory.create raises ValueError for unknown type"""
+def test_create_storage_invalid_type():
+    """StorageFactory.create raises ValueError for unknown type"""
    with pytest.raises(ValueError, match="Unknown component"):
-        StoreFactory.create("parquet")
+        StorageFactory.create("parquet")


-def test_store_multi_segment_concat(base_test_env):
-    """Multi-segment H5 data is concatenated into single tensor at load time"""
-    import os
-
+def test_json_pretokenized_without_tokenizer(base_test_env):
+    """Pre-tokenized JSON (List[List[int]]) loads without tokenizer"""
    test_dir = base_test_env["test_dir"]
-    data_dir = os.path.join(test_dir, "multi_seg")
+    data_dir = os.path.join(test_dir, "json_pretok")
    os.makedirs(data_dir, exist_ok=True)

+    json_path = os.path.join(data_dir, "data.json")
+    with open(json_path, "w", encoding="utf-8") as f:
+        json.dump({"sequence": [[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]]}, f)
+
+    dataset = DatasetFactory.load("seq", data_dir, window_size=4, storage_type="json")
+    assert len(dataset) > 0
+    assert dataset.count == 10
+
+    item = dataset[0]
+    assert item["input_ids"].tolist() == [1, 2, 3, 4]
+    assert item["target_ids"].tolist() == [2, 3, 4, 5]
+
+
+def test_load_json_skips_config_file(base_test_env):
+    """load_json skips scalar-value config files"""
+    test_dir = base_test_env["test_dir"]
+    with open(os.path.join(test_dir, "config.json"), "w") as f:
+        json.dump({"vocab_size": 1000, "dim": 16}, f)
+
+    with open(os.path.join(test_dir, "data.json"), "w") as f:
+        json.dump({"sequence": [[1, 2, 3, 4, 5]]}, f)
+
+    result = load_json(test_dir)
+    assert "sequence" in result
+    assert "vocab_size" not in result
+    assert len(result["sequence"]) == 1
+
+
+def test_base_segment_fetcher_multi_segment():
+    """fetch_data across multiple segment boundaries"""
    segs = [
        torch.tensor([1, 2, 3]),
        torch.tensor([4, 5, 6, 7]),
        torch.tensor([8, 9]),
    ]
-    save_h5(data_dir, "data", {"sequence": segs})
-
-    store = StoreFactory.create("h5")
-    store.load(data_dir)
-    assert len(store) == 9
-    result = store.fetch(2, 7, "sequence")
+    fetcher = BaseSegmentFetcher(segs)
+    assert len(fetcher) == 9
+    result = fetcher.fetch_data(2, 7)
    assert result.tolist() == [3, 4, 5, 6, 7]
-
-
-def test_save_load_bin_roundtrip(base_test_env):
-    """save_bin + load_bin roundtrip preserves data"""
-    test_dir = base_test_env["test_dir"]
-
-    data = {
-        "sequence": [torch.tensor([1, 2, 3, 4, 5], dtype=torch.int64)],
-        "loss_mask": [torch.tensor([0, 1, 1, 0, 1], dtype=torch.int64)],
-    }
-    save_bin(test_dir, data)
-    result = load_bin(test_dir)
-
-    assert "sequence" in result
-    assert "loss_mask" in result
-    assert result["sequence"][0].tolist() == [1, 2, 3, 4, 5]
-    assert result["loss_mask"][0].tolist() == [0, 1, 1, 0, 1]
-
-
-def test_mmap_store_load_and_fetch(base_test_env):
-    test_dir = base_test_env["test_dir"]
-    data = {"sequence": [_rand_seq(200)]}
-    save_bin(test_dir, data)
-
-    store = StoreFactory.create("bin")
-    store.load(test_dir)
-    assert len(store) == 200
-    assert "sequence" in store.keys
-
-    result = store.fetch(10, 20, "sequence")
-    assert result.tolist() == data["sequence"][0][10:20].tolist()
-
-
-def test_mmap_dataset_load(base_test_env):
-    test_dir = base_test_env["test_dir"]
-    data = {"sequence": [_rand_seq(200)]}
-    save_bin(test_dir, data)
-    dataset = DatasetFactory.load("seq", test_dir, window_size=64)
-    assert len(dataset) > 0
-    assert dataset.count == 200
-    assert dataset[0]["input_ids"].shape[0] == 64
-
-
-def test_normalize_empty_key():
-    """_normalize with empty tensor list does not crash"""
-    store = H5Store()
-    store._normalize({"sequence": []})
-    assert len(store) == 0
-    assert store.keys == ["sequence"]
-
-
-def test_normalize_mixed_empty_key():
-    """_normalize with empty + non-empty keys returns min=0"""
-    store = H5Store()
-    store._normalize({"sequence": [torch.tensor([1, 2, 3])], "loss_mask": []})
-    assert len(store) == 0
-    assert set(store.keys) == {"sequence", "loss_mask"}
-
-
-def test_grpo_dataset_dtype(base_test_env):
-    test_dir = base_test_env["test_dir"]
-    dummy_data = {
-        "prompts": [torch.randint(0, 100, (100,), dtype=torch.int32)],
-        "responses": [torch.randint(0, 100, (100,), dtype=torch.int32)],
-        "masks": [torch.ones(100, dtype=torch.int32)],
-        "rewards": [torch.ones(100, dtype=torch.float32)],
-    }
-    dataset = _make_seq_dataset(
-        test_dir, "grpo_dtype", train_type="grpo", data=dummy_data, window_size=32
-    )
-    item = dataset[0]
-
-    assert item["prompts"].dtype == torch.long
-    assert item["responses"].dtype == torch.long
-    assert item["masks"].dtype == torch.bool
-    assert item["rewards"].dtype == torch.float32
-
-
-def test_grpo_dataset_load(base_test_env):
-    test_dir = base_test_env["test_dir"]
-    dummy_data = {
-        "prompts": [_rand_seq(200)],
-        "responses": [_rand_seq(200)],
-        "masks": [torch.ones(200, dtype=torch.int64)],
-        "rewards": [torch.rand(200, dtype=torch.float32)],
-    }
-    dataset = _make_seq_dataset(
-        test_dir, "grpo_test", train_type="grpo", data=dummy_data
-    )
-    assert len(dataset) > 0
-    item = dataset[0]
-    assert "prompts" in item
-    assert "responses" in item
-    assert "masks" in item
-    assert "rewards" in item
-    assert item["prompts"].shape[0] == 64
-    assert item["responses"].shape[0] == 64
-
-
-def test_detect_format_bin_dir(base_test_env):
-    """detect_format returns 'bin' for directory with .bin + meta.json"""
-    test_dir = base_test_env["test_dir"]
-    save_bin(test_dir, {"sequence": [torch.randint(0, 100, (10,))]})
-    assert detect_format(test_dir) == "bin"
-
-
-def test_store_fetch_multi_key(base_test_env):
-    test_dir = base_test_env["test_dir"]
-    save_h5(
-        test_dir,
-        "multi_key",
-        {
-            "sequence": [torch.randint(0, 100, (100,), dtype=torch.int64)],
-            "loss_mask": [torch.ones(100, dtype=torch.int64)],
-        },
-    )
-    store = StoreFactory.create("h5")
-    store.load(test_dir)
-    result = store.fetch(10, 20, ["sequence", "loss_mask"])
-    assert isinstance(result, dict)
-    assert result["sequence"].shape[0] == 10
-    assert result["loss_mask"].shape[0] == 10
-
-
-def test_store_fetch_out_of_bounds(base_test_env):
-    test_dir = base_test_env["test_dir"]
-    save_h5(test_dir, "bounds", {"sequence": [torch.randint(0, 100, (50,))]})
-    store = StoreFactory.create("h5")
-    store.load(test_dir)
-    with pytest.raises(ValueError, match="out of bounds"):
-        store.fetch(-1, 10, "sequence")
-    with pytest.raises(ValueError, match="out of bounds"):
-        store.fetch(0, 51, "sequence")
-    with pytest.raises(ValueError, match="out of bounds"):
-        store.fetch(50, 50, "sequence")
-
-
-def test_dataset_load_explicit_storage_type(base_test_env):
-    test_dir = base_test_env["test_dir"]
-    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
@@ -1,369 +0,0 @@
-import pytest
-
-from astrai.config.preprocess_config import (
-    InputConfig,
-    OutputConfig,
-    PipelineConfig,
-    ProcessingConfig,
-)
-from astrai.preprocessing.builder import (
-    MaskBuilderFactory,
-    SectionedMaskBuilder,
-)
-from tests.data.conftest import (
-    _CHAT_SECTIONS,
-    _INSTRUCTION_SECTIONS,
-    _TEXT_SECTIONS,
-    make_chat_config,
-    make_dpo_chat_config,
-    make_grpo_config,
-    make_instruction_config,
-    make_text_config,
-)
-
-
-def test_chat_simple(chat_tokenizer, builder):
-    config = make_chat_config()
-    item = {
-        "messages": [
-            {"role": "system", "content": "You are helpful."},
-            {"role": "user", "content": "Hello."},
-            {"role": "assistant", "content": "Hi there!"},
-        ]
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert result is not None
-    assert "sequence" in result
-    assert "loss_mask" in result
-    assert len(result["sequence"]) == len(result["loss_mask"])
-
-    ids = chat_tokenizer.decode(result["sequence"], skip_special_tokens=False)
-    assert "system" in ids.lower() or "<|im_start|>system" in ids
-    assert "assistant" in ids.lower() or "<|im_start|>assistant" in ids
-
-    total = len(result["sequence"])
-    trained = sum(result["loss_mask"])
-    assert trained > 0
-    assert trained < total
-
-
-def test_chat_mask_only_assistant(chat_tokenizer, builder):
-    config = make_chat_config()
-    item = {
-        "messages": [
-            {"role": "user", "content": "What is 2+2?"},
-            {"role": "assistant", "content": "4"},
-        ]
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    mask = result["loss_mask"]
-    ids = result["sequence"]
-    assert len(ids) == len(mask)
-
-    trained = [i for i, m in enumerate(mask) if m == 1]
-    masked = [i for i, m in enumerate(mask) if m == 0]
-    assert len(trained) > 0
-    assert len(masked) > 0
-
-
-@pytest.mark.parametrize(
-    "mask_rules,mask_default,expect_nonzero",
-    [
-        ({"system": "mask", "user": "mask", "assistant": "mask"}, "mask", False),
-        ({}, "train", True),
-    ],
-)
-def test_chat_uniform_masking(
-    mask_rules, mask_default, expect_nonzero, chat_tokenizer, builder
-):
-    config = PipelineConfig(
-        input=InputConfig(sections=_CHAT_SECTIONS),
-        mask=mask_rules,
-        mask_default=mask_default,
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-    item = {
-        "messages": [
-            {"role": "system", "content": "You are helpful."},
-            {"role": "assistant", "content": "Hi there!"},
-        ]
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    masked_count = sum(result["loss_mask"])
-    if expect_nonzero:
-        assert masked_count > 0
-    else:
-        assert masked_count == 0
-
-
-def test_chat_empty_messages(chat_tokenizer, builder):
-    config = make_chat_config()
-    assert builder.build({"messages": []}, config, chat_tokenizer) is None
-    assert builder.build({}, config, chat_tokenizer) is None
-
-
-def test_chat_domain_extraction(chat_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_CHAT_SECTIONS),
-        mask={"assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-        output=OutputConfig(domain_key="source"),
-    )
-    item = {
-        "messages": [
-            {"role": "user", "content": "Hi"},
-            {"role": "assistant", "content": "Hello"},
-        ],
-        "source": "wiki",
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert result["domain"] == "wiki"
-
-
-def test_chat_truncation(chat_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_CHAT_SECTIONS),
-        mask={"assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=10),
-    )
-    item = {
-        "messages": [
-            {
-                "role": "user",
-                "content": "Tell me a very long story about dragons and knights and magic.",
-            },
-            {"role": "assistant", "content": "Sure! Here is a tale..."},
-        ]
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert len(result["sequence"]) <= 10
-    assert len(result["loss_mask"]) == len(result["sequence"])
-
-
-def test_instruction_basic(test_tokenizer, builder):
-    config = make_instruction_config()
-    item = {"prompt": "Translate to French: Hello", "response": "Bonjour"}
-    result = builder.build(item, config, test_tokenizer)
-    assert result is not None
-    assert len(result["sequence"]) == len(result["loss_mask"])
-
-
-def test_instruction_prompt_masked(test_tokenizer, builder):
-    config = make_instruction_config()
-    item = {"prompt": "hello", "response": "world"}
-    result = builder.build(item, config, test_tokenizer)
-    mask = result["loss_mask"]
-    ids = result["sequence"]
-
-    prompt_ids = test_tokenizer.encode("hello", add_special_tokens=True)
-    p_len = min(len(prompt_ids), len(ids))
-    assert all(m == 0 for m in mask[:p_len])
-    if p_len < len(ids):
-        assert all(m == 1 for m in mask[p_len:])
-
-
-def test_instruction_train_on_prompt(test_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(
-            sections=[
-                {"field": "prompt", "action": "train", "add_special_tokens": True},
-                {"field": "response", "action": "mask"},
-            ]
-        ),
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-    item = {"prompt": "hello", "response": "world"}
-    result = builder.build(item, config, test_tokenizer)
-    mask = result["loss_mask"]
-    ids = result["sequence"]
-
-    prompt_ids = test_tokenizer.encode("hello", add_special_tokens=True)
-    p_len = min(len(prompt_ids), len(ids))
-    assert all(m == 1 for m in mask[:p_len])
-
-
-def test_text_basic(test_tokenizer, builder):
-    config = make_text_config()
-    item = {"text": "Hello world. This is a test document."}
-    result = builder.build(item, config, test_tokenizer)
-    assert result is not None
-    assert "sequence" in result
-    assert len(result["sequence"]) > 0
-    assert "loss_mask" not in result
-
-
-def test_text_empty(test_tokenizer, builder):
-    config = make_text_config()
-    assert builder.build({"text": ""}, config, test_tokenizer) is None
-    assert builder.build({"text": "   "}, config, test_tokenizer) is None
-
-
-def test_text_too_short(test_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_TEXT_SECTIONS),
-        preprocessing=ProcessingConfig(min_chars=100),
-    )
-    assert builder.build({"text": "short"}, config, test_tokenizer) is None
-
-
-def test_text_truncation(test_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_TEXT_SECTIONS),
-        preprocessing=ProcessingConfig(max_seq_len=3, min_chars=1),
-    )
-    item = {"text": "This is a very long text that should be truncated"}
-    result = builder.build(item, config, test_tokenizer)
-    assert len(result["sequence"]) <= 3
-
-
-def test_sectioned_chat(chat_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_CHAT_SECTIONS),
-        mask={"system": "mask", "user": "mask", "assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-    )
-    item = {
-        "messages": [
-            {"role": "user", "content": "What is 2+2?"},
-            {"role": "assistant", "content": "4"},
-        ]
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert result is not None
-    assert len(result["sequence"]) == len(result["loss_mask"])
-    assert sum(result["loss_mask"]) > 0
-    assert 0 in result["loss_mask"]
-
-
-def test_sectioned_instruction(test_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_INSTRUCTION_SECTIONS),
-        preprocessing=ProcessingConfig(max_seq_len=2048, min_chars=0),
-    )
-    item = {"prompt": "Q: Why?", "response": "A: Because."}
-    result = builder.build(item, config, test_tokenizer)
-    assert result is not None
-    mask = result["loss_mask"]
-    assert mask[0] == 0
-    assert mask[-1] == 1
-
-
-def test_sectioned_text(test_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_TEXT_SECTIONS),
-        preprocessing=ProcessingConfig(max_seq_len=2048, min_chars=1),
-    )
-    item = {"text": "Hello world, this is a test."}
-    result = builder.build(item, config, test_tokenizer)
-    assert result is not None
-    assert "loss_mask" not in result
-
-
-def test_sectioned_text_too_short(test_tokenizer, builder):
-    config = PipelineConfig(
-        input=InputConfig(sections=_TEXT_SECTIONS),
-        preprocessing=ProcessingConfig(max_seq_len=2048, min_chars=100),
-    )
-    assert builder.build({"text": "short"}, config, test_tokenizer) is None
-
-
-def test_factory_registered():
-    names = MaskBuilderFactory.list_registered()
-    assert "sectioned" in names
-
-
-def test_factory_create():
-    builder_obj = MaskBuilderFactory.create("sectioned")
-    assert isinstance(builder_obj, SectionedMaskBuilder)
-
-
-def test_dpo_chat_basic(chat_tokenizer, builder):
-    config = make_dpo_chat_config()
-    item = {
-        "chosen": [
-            {"role": "user", "content": "What is 2+2?"},
-            {"role": "assistant", "content": "4"},
-        ],
-        "rejected": [
-            {"role": "user", "content": "What is 2+2?"},
-            {"role": "assistant", "content": "5"},
-        ],
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert result is not None
-    assert "chosen" in result
-    assert "rejected" in result
-    assert "chosen_mask" in result
-    assert "rejected_mask" in result
-    assert len(result["chosen"]) == len(result["chosen_mask"])
-    assert len(result["rejected"]) == len(result["rejected_mask"])
-    assert sum(result["chosen_mask"]) > 0
-    assert sum(result["rejected_mask"]) > 0
-
-
-def test_dpo_chosen_only_trained(chat_tokenizer, builder):
-    config = make_dpo_chat_config()
-    item = {
-        "chosen": [
-            {"role": "user", "content": "Hi"},
-            {"role": "assistant", "content": "Hello"},
-        ],
-        "rejected": [
-            {"role": "user", "content": "Hi"},
-            {"role": "assistant", "content": "Go away"},
-        ],
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert 0 in result["chosen_mask"]
-    assert 1 in result["chosen_mask"]
-    assert 0 in result["rejected_mask"]
-    assert 1 in result["rejected_mask"]
-
-
-def test_dpo_missing_field_is_none(chat_tokenizer, builder):
-    config = make_dpo_chat_config()
-    assert builder.build({"chosen": [], "rejected": []}, config, chat_tokenizer) is None
-
-
-def test_grpo_basic(chat_tokenizer, builder):
-    config = make_grpo_config()
-    item = {
-        "prompt": [{"role": "user", "content": "What is 2+2?"}],
-        "responses": ["4", "The answer is four", "Four", "2+2=4"],
-        "rewards": [1.0, 0.5, 0.8, 0.2],
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert result is not None
-    assert "prompts" in result
-    assert "responses" in result
-    assert "masks" in result
-    assert "rewards" in result
-    assert len(result["responses"]) == len(result["masks"])
-    assert result["rewards"] == [1.0, 0.5, 0.8, 0.2]
-
-
-def test_grpo_response_tokens_all_trained(chat_tokenizer, builder):
-    config = make_grpo_config()
-    item = {
-        "prompt": [{"role": "user", "content": "Q"}],
-        "responses": ["A", "B"],
-        "rewards": [0.8, 0.2],
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    masks = result["masks"]
-    assert all(m == 1 for m in masks)
-    assert len(masks) == len(result["responses"])
-
-
-def test_grpo_single_reward(chat_tokenizer, builder):
-    config = make_grpo_config()
-    item = {
-        "prompt": [{"role": "user", "content": "Q"}],
-        "responses": ["A"],
-        "rewards": 0.9,
-    }
-    result = builder.build(item, config, chat_tokenizer)
-    assert result["rewards"] == [0.9]
@@ -1,77 +0,0 @@
-import os
-
-from astrai.config.preprocess_config import (
-    InputConfig,
-    PipelineConfig,
-)
-from tests.data.conftest import (
-    _INSTRUCTION_SECTIONS,
-    _TEXT_SECTIONS,
-    make_dpo_chat_config,
-)
-
-
-def test_default_values():
-    config = PipelineConfig()
-    assert config.version == 1
-    assert config.mask == {}
-    assert config.mask_default == "mask"
-    assert config.preprocessing.max_seq_len == 2048
-    assert config.output.storage_format == "bin"
-    assert config.input.sections is None
-
-
-def test_from_dict_flat():
-    data = {
-        "version": 1,
-        "input": {
-            "sections": [{"field": "messages", "action": "$role", "template": True}]
-        },
-        "mask": {"system": "mask", "assistant": "train"},
-        "mask_default": "mask",
-        "preprocessing": {"max_seq_len": 1024},
-        "output": {"storage_format": "h5"},
-    }
-    config = PipelineConfig.from_dict(data)
-    assert config.input.sections == [
-        {"field": "messages", "action": "$role", "template": True}
-    ]
-    assert config.mask == {"system": "mask", "assistant": "train"}
-    assert config.preprocessing.max_seq_len == 1024
-    assert config.output.storage_format == "h5"
-
-
-def test_to_dict_roundtrip():
-    config = PipelineConfig(
-        input=InputConfig(sections=_INSTRUCTION_SECTIONS),
-        mask={"prompt": "mask", "response": "train"},
-        mask_default="mask",
-    )
-    d = config.to_dict()
-    config2 = PipelineConfig.from_dict(d)
-    assert config2.input.sections == _INSTRUCTION_SECTIONS
-    assert config2.mask == {"prompt": "mask", "response": "train"}
-
-
-def test_to_file_from_file(temp_dir):
-    config = PipelineConfig(
-        input=InputConfig(sections=_TEXT_SECTIONS),
-        mask={"text": "train"},
-        mask_default="mask",
-    )
-    path = os.path.join(temp_dir, "config.json")
-    config.to_file(path)
-    loaded = PipelineConfig.from_file(path)
-    assert loaded.input.sections == _TEXT_SECTIONS
-    assert loaded.mask == {"text": "train"}
-
-
-def test_dpo_config_roundtrip(temp_dir):
-    config = make_dpo_chat_config()
-    path = os.path.join(temp_dir, "config.json")
-    config.to_file(path)
-    loaded = PipelineConfig.from_file(path)
-    assert loaded.input.sources is not None
-    assert "chosen" in loaded.input.sources
-    assert "rejected" in loaded.input.sources
-    assert loaded.input.sections is None
@@ -1,264 +0,0 @@
-import json
-import os
-
-from astrai.config.preprocess_config import (
-    InputConfig,
-    OutputConfig,
-    PipelineConfig,
-    ProcessingConfig,
-)
-from astrai.preprocessing.pipeline import Pipeline, filter_by_length
-from tests.data.conftest import (
-    _CHAT_SECTIONS,
-    _INSTRUCTION_SECTIONS,
-    _TEXT_SECTIONS,
-    make_dpo_chat_config,
-    make_grpo_no_template_config,
-)
-
-
-def test_filter_by_length():
-    assert filter_by_length("hello world", min_len=5)
-    assert not filter_by_length("hi", min_len=5)
-    assert not filter_by_length("x" * 100, max_len=50)
-    assert filter_by_length("just right", min_len=5, max_len=20)
-
-
-def test_full_chat_pipeline(temp_dir, chat_tokenizer_dir):
-    jsonl_path = os.path.join(temp_dir, "chat.jsonl")
-    with open(jsonl_path, "w", encoding="utf-8") as f:
-        f.write(
-            json.dumps(
-                {
-                    "messages": [
-                        {"role": "system", "content": "You are helpful."},
-                        {"role": "user", "content": "Hi."},
-                        {"role": "assistant", "content": "Hello!"},
-                    ]
-                }
-            )
-            + "\n"
-        )
-        f.write(
-            json.dumps(
-                {
-                    "messages": [
-                        {"role": "user", "content": "What is 2+2?"},
-                        {"role": "assistant", "content": "4"},
-                    ]
-                }
-            )
-            + "\n"
-        )
-
-    config = PipelineConfig(
-        input=InputConfig(sections=_CHAT_SECTIONS),
-        mask={"system": "mask", "user": "mask", "assistant": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-        output=OutputConfig(storage_format="bin", domain_key=None),
-    )
-
-    out_dir = os.path.join(temp_dir, "output")
-    Pipeline(
-        config=config,
-        input_paths=[jsonl_path],
-        output_dir=out_dir,
-        tokenizer_path=chat_tokenizer_dir,
-    ).run()
-
-    meta_path = os.path.join(out_dir, "__default__", "shard_0000", "meta.json")
-    assert os.path.exists(meta_path)
-    with open(meta_path, "r") as f:
-        meta = json.load(f)
-    assert "sequence" in meta
-    assert "loss_mask" in meta
-    assert meta["sequence"]["dtype"] == "int32"
-    assert meta["loss_mask"]["dtype"] == "int32"
-
-
-def test_full_text_pipeline(temp_dir, tokenizer_dir):
-    jsonl_path = os.path.join(temp_dir, "text.jsonl")
-    with open(jsonl_path, "w", encoding="utf-8") as f:
-        f.write(
-            json.dumps(
-                {
-                    "text": "Hello world this is a test document with enough characters to pass the minimum length filter."
-                }
-            )
-            + "\n"
-        )
-        f.write(
-            json.dumps(
-                {
-                    "text": "Another document for testing purposes with sufficient length to be processed."
-                }
-            )
-            + "\n"
-        )
-
-    config = PipelineConfig(
-        input=InputConfig(sections=_TEXT_SECTIONS),
-        preprocessing=ProcessingConfig(max_seq_len=2048, min_chars=10),
-        output=OutputConfig(storage_format="bin"),
-    )
-
-    out_dir = os.path.join(temp_dir, "output")
-    Pipeline(
-        config=config,
-        input_paths=[jsonl_path],
-        output_dir=out_dir,
-        tokenizer_path=tokenizer_dir,
-    ).run()
-
-    meta_path = os.path.join(out_dir, "__default__", "shard_0000", "meta.json")
-    assert os.path.exists(meta_path)
-    with open(meta_path, "r") as f:
-        meta = json.load(f)
-    assert "sequence" in meta
-    assert "loss_mask" not in meta
-
-
-def test_full_instruction_pipeline(temp_dir, tokenizer_dir):
-    jsonl_path = os.path.join(temp_dir, "instruct.jsonl")
-    with open(jsonl_path, "w", encoding="utf-8") as f:
-        f.write(
-            json.dumps(
-                {
-                    "prompt": "Tell me a joke",
-                    "response": "Why did the chicken cross the road?",
-                }
-            )
-            + "\n"
-        )
-        f.write(
-            json.dumps(
-                {
-                    "prompt": "What is AI?",
-                    "response": "Artificial Intelligence is a field of computer science.",
-                }
-            )
-            + "\n"
-        )
-
-    config = PipelineConfig(
-        input=InputConfig(sections=_INSTRUCTION_SECTIONS),
-        mask={"prompt": "mask", "response": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-        output=OutputConfig(storage_format="bin"),
-    )
-
-    out_dir = os.path.join(temp_dir, "output")
-    Pipeline(
-        config=config,
-        input_paths=[jsonl_path],
-        output_dir=out_dir,
-        tokenizer_path=tokenizer_dir,
-    ).run()
-
-    meta_path = os.path.join(out_dir, "__default__", "shard_0000", "meta.json")
-    assert os.path.exists(meta_path)
-    with open(meta_path, "r") as f:
-        meta = json.load(f)
-    assert "sequence" in meta
-    assert "loss_mask" in meta
-
-
-def test_dtype_override(temp_dir, tokenizer_dir):
-    jsonl_path = os.path.join(temp_dir, "data.jsonl")
-    with open(jsonl_path, "w", encoding="utf-8") as f:
-        f.write(json.dumps({"prompt": "Q", "response": "A"}) + "\n")
-
-    config = PipelineConfig(
-        input=InputConfig(sections=_INSTRUCTION_SECTIONS),
-        mask={"prompt": "mask", "response": "train"},
-        mask_default="mask",
-        preprocessing=ProcessingConfig(max_seq_len=2048),
-        output=OutputConfig(storage_format="bin", dtype={"loss_mask": "bool"}),
-    )
-
-    out_dir = os.path.join(temp_dir, "output")
-    Pipeline(
-        config=config,
-        input_paths=[jsonl_path],
-        output_dir=out_dir,
-        tokenizer_path=tokenizer_dir,
-    ).run()
-
-    meta_path = os.path.join(out_dir, "__default__", "shard_0000", "meta.json")
-    with open(meta_path, "r") as f:
-        meta = json.load(f)
-    assert meta["sequence"]["dtype"] == "int32"
-    assert meta["loss_mask"]["dtype"] == "bool"
-
-
-def test_dpo_pipeline(temp_dir, chat_tokenizer_dir):
-    jsonl_path = os.path.join(temp_dir, "dpo.jsonl")
-    with open(jsonl_path, "w", encoding="utf-8") as f:
-        f.write(
-            json.dumps(
-                {
-                    "chosen": [
-                        {"role": "user", "content": "Hi."},
-                        {"role": "assistant", "content": "Hello!"},
-                    ],
-                    "rejected": [
-                        {"role": "user", "content": "Hi."},
-                        {"role": "assistant", "content": "Go away."},
-                    ],
-                }
-            )
-            + "\n"
-        )
-
-    out_dir = os.path.join(temp_dir, "output")
-    Pipeline(
-        config=make_dpo_chat_config(),
-        input_paths=[jsonl_path],
-        output_dir=out_dir,
-        tokenizer_path=chat_tokenizer_dir,
-    ).run()
-
-    meta_path = os.path.join(out_dir, "__default__", "shard_0000", "meta.json")
-    assert os.path.exists(meta_path)
-    with open(meta_path, "r") as f:
-        meta = json.load(f)
-    assert "chosen" in meta
-    assert "rejected" in meta
-    assert "chosen_mask" in meta
-    assert "rejected_mask" in meta
-    assert "sequence" not in meta
-
-
-def test_grpo_pipeline(temp_dir, tokenizer_dir):
-    jsonl_path = os.path.join(temp_dir, "grpo.jsonl")
-    with open(jsonl_path, "w", encoding="utf-8") as f:
-        f.write(
-            json.dumps(
-                {
-                    "prompt": "Question?",
-                    "responses": ["Answer A", "Answer B"],
-                    "rewards": [0.8, 0.3],
-                }
-            )
-            + "\n"
-        )
-
-    out_dir = os.path.join(temp_dir, "output")
-    Pipeline(
-        config=make_grpo_no_template_config(),
-        input_paths=[jsonl_path],
-        output_dir=out_dir,
-        tokenizer_path=tokenizer_dir,
-    ).run()
-
-    meta_path = os.path.join(out_dir, "__default__", "shard_0000", "meta.json")
-    assert os.path.exists(meta_path)
-    with open(meta_path, "r") as f:
-        meta = json.load(f)
-    assert "prompts" in meta
-    assert "responses" in meta
-    assert "masks" in meta
-    assert "rewards" in meta
-    assert "sequence" not in meta
@@ -5,22 +5,21 @@ from unittest.mock import MagicMock
 import pytest
 from fastapi.testclient import TestClient

-from astrai.inference import get_app
+from astrai.inference import app


@pytest.fixture
 def client():
    """Provide a test client for the FastAPI app."""
-    _app = get_app()
-    _app.state.server_config = {
+    app.state.server_config = {
        "device": "cpu",
        "dtype": "bfloat16",
        "param_path": None,
        "max_batch_size": 1,
        "_test": True,
    }
-    _app.state.engine = None
-    return TestClient(_app)
+    app.state.engine = None
+    return TestClient(app)


@pytest.fixture
@@ -50,5 +49,5 @@ def mock_engine():
@pytest.fixture
 def loaded_model(client, mock_engine):
    """Simulate that the engine is loaded."""
-    get_app().state.engine = mock_engine
+    app.state.engine = mock_engine
    return mock_engine
@@ -4,7 +4,7 @@ import torch

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


 def test_kv_cache_task_extend_allocates():
-    cache = PageCache(
+    cache = KVCache(
        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 = PageCache(
+    cache = KVCache(
        n_layers=1,
        n_pages=2,
        page_size=64,
@@ -1,286 +0,0 @@
-"""Unit tests for protocol builders, StopChecker, GenContext, StopInfo."""
-
-import json
-from unittest.mock import MagicMock
-
-import pytest
-
-from astrai.inference.api.anthropic import AnthropicResponseBuilder
-from astrai.inference.api.openai import OpenAIResponseBuilder
-from astrai.inference.api.protocol import GenContext, StopChecker, StopInfo
-from astrai.inference.engine import GenerationRequest
-
-
-def _make_ctx(**kwargs):
-    defaults = {
-        "resp_id": "test-123",
-        "created": 1000,
-        "model": "test-model",
-        "prompt_tokens": 10,
-        "completion_tokens": 5,
-    }
-    defaults.update(kwargs)
-    return GenContext(**defaults)
-
-
-def _sse_payloads(events):
-    payloads = []
-    for chunk in events:
-        for line in chunk.strip().split("\n"):
-            if line.startswith("data: "):
-                try:
-                    payloads.append(json.loads(line[6:]))
-                except json.JSONDecodeError:
-                    pass
-    return payloads
-
-
-class TestStopChecker:
-    def test_check_finds_match(self):
-        sc = StopChecker(["stop", "end"])
-        assert sc.check("hello stop world") == "stop"
-
-    def test_check_returns_none_when_no_match(self):
-        sc = StopChecker(["stop"])
-        assert sc.check("hello world") is None
-
-    def test_check_empty_sequences(self):
-        sc = StopChecker([])
-        assert sc.check("hello") is None
-
-
-class TestGenContext:
-    def test_defaults(self):
-        ctx = GenContext(resp_id="a", created=1, model="m", prompt_tokens=10)
-        assert ctx.completion_tokens == 0
-
-    def test_fields_mutable(self):
-        ctx = GenContext(resp_id="a", created=1, model="m", prompt_tokens=10)
-        ctx.completion_tokens = 42
-        assert ctx.completion_tokens == 42
-
-
-class TestStopInfo:
-    def test_defaults(self):
-        s = StopInfo()
-        assert s.matched is None
-        assert s.body == ""
-        assert s.yielded == ""
-
-    def test_with_values(self):
-        s = StopInfo(matched="stop", body="hello stop", yielded="hello ")
-        assert s.matched == "stop"
-        assert s.body == "hello stop"
-        assert s.yielded == "hello "
-
-
-class TestOpenAIResponseBuilder:
-    @pytest.fixture
-    def builder(self):
-        builder = OpenAIResponseBuilder()
-        req = MagicMock()
-        req.messages = [MagicMock(role="user", content="Hello")]
-        req.stop = None
-        req.model = "astrai"
-        engine = MagicMock()
-        engine.tokenizer.apply_chat_template.return_value = "Hello"
-        builder.prepare(req, engine)
-        return builder
-
-    def test_prepare_returns_prompt_ctx_stops(self, builder):
-        req = MagicMock()
-        req.messages = [MagicMock(role="user", content="Hi")]
-        req.stop = ["END"]
-        req.model = "gpt"
-        engine = MagicMock()
-        engine.tokenizer.apply_chat_template.return_value = "Hi"
-        prompt, ctx, stops = builder.prepare(req, engine)
-        assert prompt == "Hi"
-        assert ctx.model == "gpt"
-        assert ctx.prompt_tokens == 0
-        assert stops == ["END"]
-
-    def test_prepare_no_stop_returns_empty_list(self, builder):
-        req = MagicMock()
-        req.messages = []
-        req.stop = None
-        req.model = "x"
-        engine = MagicMock()
-        engine.tokenizer.apply_chat_template.return_value = ""
-        _, _, stops = builder.prepare(req, engine)
-        assert stops == []
-
-    def test_format_stream_start(self, builder):
-        ctx = _make_ctx()
-        events = builder.format_stream_start(ctx)
-        payloads = _sse_payloads(events)
-        assert len(payloads) == 1
-        p = payloads[0]
-        assert p["object"] == "chat.completion.chunk"
-        assert p["choices"][0]["delta"]["role"] == "assistant"
-        assert p["choices"][0]["finish_reason"] is None
-
-    def test_format_chunk(self, builder):
-        events = builder.format_chunk("hello", body="hello")
-        payload = json.loads(events[0].split("data: ", 1)[1])
-        assert payload["choices"][0]["delta"]["content"] == "hello"
-        assert payload["choices"][0]["finish_reason"] is None
-
-    def test_format_stream_end(self, builder):
-        ctx = _make_ctx(completion_tokens=5)
-        stop = StopInfo(matched="stop")
-        events = builder.format_stream_end(ctx, stop)
-        payloads = _sse_payloads(events)
-        finish = payloads[0]
-        assert finish["choices"][0]["finish_reason"] == "stop"
-        usage = payloads[1]
-        assert usage["completion_tokens"] == 5
-        assert usage["total_tokens"] == 15
-
-    def test_format_response(self, builder):
-        ctx = _make_ctx()
-        stop = StopInfo()
-        resp = builder.format_response(ctx, "hello", stop)
-        assert resp["object"] == "chat.completion"
-        assert resp["choices"][0]["message"]["content"] == "hello"
-        assert resp["usage"]["prompt_tokens"] == 10
-
-
-class TestAnthropicResponseBuilder:
-    @pytest.fixture
-    def builder(self):
-        builder = AnthropicResponseBuilder()
-        req = MagicMock()
-        req.messages = [MagicMock(role="user", content="Hello")]
-        req.model = "claude"
-        engine = MagicMock()
-        engine.tokenizer.apply_chat_template.return_value = "Hello"
-        req.system = None
-        builder.prepare(req, engine)
-        return builder
-
-    def test_prepare_messages(self, builder):
-        req = MagicMock()
-        req.messages = [MagicMock(role="user", content="Hi")]
-        req.model = "claude"
-        req.system = None
-        req.stop_sequences = None
-        engine = MagicMock()
-        engine.tokenizer.apply_chat_template.return_value = "Hi"
-        prompt, ctx, stops = builder.prepare(req, engine)
-        assert prompt == "Hi"
-        assert stops == []
-
-    def test_prepare_with_stop_sequences(self, builder):
-        req = MagicMock()
-        req.messages = []
-        req.model = "x"
-        req.stop_sequences = ["stop", "end"]
-        req.system = None
-        engine = MagicMock()
-        engine.tokenizer.apply_chat_template.return_value = ""
-        _, _, stops = builder.prepare(req, engine)
-        assert stops == ["stop", "end"]
-
-    def test_format_stream_start(self, builder):
-        ctx = _make_ctx(prompt_tokens=3)
-        events = builder.format_stream_start(ctx)
-        payloads = _sse_payloads(events)
-        assert len(payloads) == 2
-        assert payloads[0]["type"] == "message_start"
-        assert payloads[0]["message"]["usage"]["input_tokens"] == 3
-        assert payloads[1]["type"] == "content_block_start"
-
-    def test_format_chunk(self, builder):
-        events = builder.format_chunk("tok", body="tok")
-        payload = json.loads(events[0].split("data: ", 1)[1])
-        assert payload["type"] == "content_block_delta"
-        assert payload["delta"]["text"] == "tok"
-
-    def test_format_stream_end_no_stop(self, builder):
-        ctx = _make_ctx(completion_tokens=3)
-        stop = StopInfo()
-        events = builder.format_stream_end(ctx, stop)
-        payloads = _sse_payloads(events)
-        # content_block_stop, message_delta, message_stop
-        types = [p["type"] for p in payloads]
-        assert types == ["content_block_stop", "message_delta", "message_stop"]
-        assert payloads[1]["delta"]["stop_reason"] == "end_turn"
-
-    def test_format_stream_end_with_stop_trims_and_emits_remaining(self, builder):
-        ctx = _make_ctx(completion_tokens=7)
-        stop = StopInfo(
-            matched="END",
-            body="Hello world END extra",
-            yielded="Hello ",
-        )
-        events = builder.format_stream_end(ctx, stop)
-        payloads = _sse_payloads(events)
-        # unyielded delta, content_block_stop, message_delta, message_stop
-        types = [p["type"] for p in payloads]
-        assert types == [
-            "content_block_delta",
-            "content_block_stop",
-            "message_delta",
-            "message_stop",
-        ]
-        assert payloads[0]["delta"]["text"] == "world "
-        assert payloads[2]["delta"]["stop_reason"] == "stop_sequence"
-        assert payloads[2]["delta"]["stop_sequence"] == "END"
-
-    def test_format_stream_end_stop_trimmed_already_yielded(self, builder):
-        ctx = _make_ctx()
-        stop = StopInfo(
-            matched="END",
-            body="Hello END",
-            yielded="Hello ",
-        )
-        events = builder.format_stream_end(ctx, stop)
-        payloads = _sse_payloads(events)
-        # No unyielded delta (everything already sent)
-        types = [p["type"] for p in payloads]
-        assert types == ["content_block_stop", "message_delta", "message_stop"]
-
-    def test_format_response_with_stop_trims_content(self, builder):
-        ctx = _make_ctx()
-        stop = StopInfo(matched="STOP", body="text STOP extra", yielded="text ")
-        resp = builder.format_response(ctx, "text STOP extra", stop)
-        assert resp["content"][0]["text"] == "text "
-        assert resp["stop_reason"] == "stop_sequence"
-        assert resp["stop_sequence"] == "STOP"
-
-    def test_format_response_no_stop(self, builder):
-        ctx = _make_ctx()
-        stop = StopInfo()
-        resp = builder.format_response(ctx, "full text", stop)
-        assert resp["content"][0]["text"] == "full text"
-        assert resp["stop_reason"] == "end_turn"
-
-
-class TestGenerationRequestValidation:
-    def test_valid_params(self):
-        gr = GenerationRequest(
-            messages=[{"role": "user", "content": "hi"}],
-            top_k=50,
-            top_p=0.9,
-            temperature=0.7,
-        )
-        assert gr.top_k == 50
-
-    def test_invalid_top_p_raises(self):
-        with pytest.raises(ValueError, match="top_p"):
-            GenerationRequest(messages=[{"role": "user", "content": "hi"}], top_p=1.5)
-
-    def test_invalid_top_k_raises(self):
-        with pytest.raises(ValueError, match="top_k"):
-            GenerationRequest(messages=[{"role": "user", "content": "hi"}], top_k=-1)
-
-    def test_invalid_temperature_raises(self):
-        with pytest.raises(ValueError, match="temperature"):
-            GenerationRequest(
-                messages=[{"role": "user", "content": "hi"}], temperature=-0.1
-            )
-
-    def test_top_k_zero_valid(self):
-        gr = GenerationRequest(messages=[{"role": "user", "content": "hi"}], top_k=0)
-        assert gr.top_k == 0
@@ -173,21 +173,3 @@ def test_scheduler_concurrent_get_stats(mock_model_and_tokenizer):
    for stats in results["stats"]:
        assert "total_tasks" in stats
        assert stats["total_tasks"] >= 0
-
-
-def test_prefill_skips_fully_cached_tasks(mock_model_and_tokenizer):
-    """Tasks whose entire prompt is cached skip the prefill phase."""
-    mock_model, mock_tokenizer = mock_model_and_tokenizer
-
-    with patch("astrai.inference.core.scheduler.AutoModel"):
-        with patch("astrai.inference.core.scheduler.AutoTokenizer"):
-            scheduler = InferenceScheduler(
-                model=mock_model,
-                tokenizer=mock_tokenizer,
-                max_batch_size=4,
-                device="cpu",
-            )
-
-    task_id = scheduler.add_task("short prompt", stream_callback=lambda t: None)
-    scheduler.stop()
-    assert task_id.startswith("task_")
@@ -2,12 +2,12 @@

 import pytest

-from astrai.inference import get_app
+from astrai.inference import app


 def test_health_no_model(client):
    """GET /health should return 200 even when engine not loaded."""
-    get_app().state.engine = None
+    app.state.engine = None
    response = client.get("/health")
    assert response.status_code == 200
    data = response.json()
@@ -30,7 +30,7 @@ def test_chat_completions_non_stream(client, loaded_model):
    async def async_gen():
        yield "Assistant reply"

-    get_app().state.engine = loaded_model
+    app.state.engine = loaded_model
    loaded_model.generate_async.return_value = async_gen()
    response = client.post(
        "/v1/chat/completions",
@@ -56,7 +56,7 @@ def test_chat_completions_stream(client, loaded_model):
        yield "cumulative1"
        yield "cumulative2"

-    get_app().state.engine = loaded_model
+    app.state.engine = loaded_model
    loaded_model.generate_async.return_value = async_gen()
    response = client.post(
        "/v1/chat/completions",
@@ -83,7 +83,7 @@ def test_messages_non_stream(client, loaded_model):
    async def async_gen():
        yield "Assistant reply"

-    get_app().state.engine = loaded_model
+    app.state.engine = loaded_model
    loaded_model.generate_async.return_value = async_gen()
    response = client.post(
        "/v1/messages",
@@ -111,7 +111,7 @@ def test_messages_stream(client, loaded_model):
        yield "cumulative1"
        yield "cumulative2"

-    get_app().state.engine = loaded_model
+    app.state.engine = loaded_model
    loaded_model.generate_async.return_value = async_gen()
    response = client.post(
        "/v1/messages",
@@ -141,7 +141,7 @@ def test_messages_with_system(client, loaded_model):
    async def async_gen():
        yield "Reply"

-    get_app().state.engine = loaded_model
+    app.state.engine = loaded_model
    loaded_model.generate_async.return_value = async_gen()
    response = client.post(
        "/v1/messages",
@@ -157,60 +157,5 @@ def test_messages_with_system(client, loaded_model):
    assert data["type"] == "message"


-def test_chat_completions_stop_sequence(client, loaded_model):
-    """POST /v1/chat/completions with stop parameter truncates at stop sequence."""
-
-    async def async_gen():
-        yield "Hello"
-        yield "X"
-        yield "world"
-
-    get_app().state.engine = loaded_model
-    loaded_model.generate_async.return_value = async_gen()
-    response = client.post(
-        "/v1/chat/completions",
-        json={
-            "messages": [{"role": "user", "content": "Hello"}],
-            "max_tokens": 100,
-            "stream": False,
-            "stop": ["X"],
-        },
-    )
-    assert response.status_code == 200
-    data = response.json()
-    content = data["choices"][0]["message"]["content"]
-    assert "X" in content
-    assert "world" not in content
-
-
-def test_chat_completions_stop_sequence_stream(client, loaded_model):
-    """POST /v1/chat/completions with stop parameter truncates SSE stream."""
-
-    async def async_gen():
-        yield "Hello"
-        yield "X"
-        yield "world"
-
-    get_app().state.engine = loaded_model
-    loaded_model.generate_async.return_value = async_gen()
-    response = client.post(
-        "/v1/chat/completions",
-        json={
-            "messages": [{"role": "user", "content": "Hello"}],
-            "max_tokens": 100,
-            "stream": True,
-            "stop": ["X"],
-        },
-        headers={"Accept": "text/event-stream"},
-    )
-    assert response.status_code == 200
-    content = response.content.decode("utf-8")
-    assert "Hello" in content
-    assert "world" not in content
-    assert any(
-        "finish_reason" in line for line in content.split("\n") if "stop" in line
-    )
-
-
 if __name__ == "__main__":
    pytest.main([__file__, "-v"])
@@ -1,608 +0,0 @@
-"""Unit tests for tool call parsers."""
-
-import pytest
-
-from astrai.inference.api.tool_parser import (
-    _TOOL_CALL_HEAD_RE,
-    BaseToolParser,
-    SimpleJsonToolParser,
-    ToolParserFactory,
-    _find_partial_tool_call,
-    _find_tool_calls,
-    _scan_json,
-)
-
-
-@pytest.mark.parametrize(
-    "text,expected_complete,check_end_eq_len",
-    [
-        ('{"key": "value"}', True, True),
-        ('{"outer": {"inner": 1}}', True, True),
-        ('{"key": "value"', False, False),
-        ('{"outer": {"inner": 1}', False, False),
-        ('{"key": "a{b}c"} extra', True, False),
-        (r'{"key": "a\"b"}', True, False),
-        ('{"a": {"b": {"c": {"d": {"e": 5}}}}}', True, True),
-        ('{"items": [{"x": 1}, {"x": 2}]}', True, True),
-        ('{"fn": "function() { return 1; }"}', True, False),
-        ('{"key": "\u5317\u4eac"}', True, False),
-    ],
-)
-def test_scan_json(text, expected_complete, check_end_eq_len):
-    end, complete = _scan_json(text, 0)
-    assert complete is expected_complete
-    if check_end_eq_len:
-        assert end == len(text)
-
-
-def test_find_single_tool_call():
-    text = '{"name": "get_weather", "arguments": {"city": "Beijing"}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "get_weather"
-    assert '"city"' in results[0]["args"]
-    assert results[0]["complete"] is True
-
-
-def test_find_text_before_tool_call():
-    text = 'Some text {"name": "func", "arguments": {}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["start"] > 0
-
-
-def test_find_multiple_tool_calls():
-    text = '{"name": "f1", "arguments": {"a": 1}}{"name": "f2", "arguments": {"b": 2}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 2
-    assert results[0]["name"] == "f1"
-    assert results[1]["name"] == "f2"
-
-
-def test_find_no_tool_call():
-    results = _find_tool_calls("Hello, how are you?")
-    assert len(results) == 0
-
-
-def test_find_non_tool_json_skipped():
-    results = _find_tool_calls('{"not_a_tool": true}')
-    assert len(results) == 0
-
-
-def test_find_no_arguments_field():
-    results = _find_tool_calls('{"name": "simple_func"}')
-    assert len(results) == 1
-    assert results[0]["name"] == "simple_func"
-    assert results[0]["args"] == ""
-
-
-def test_find_deeply_nested_arguments():
-    text = '{"name": "deep", "arguments": {"a": {"b": {"c": {"d": 4}}}}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "deep"
-    assert '"d": 4' in results[0]["args"]
-
-
-def test_find_arguments_with_boolean_and_null():
-    text = '{"name": "flags", "arguments": {"active": true, "count": 0, "nick": null}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "flags"
-    assert "true" in results[0]["args"]
-    assert "null" in results[0]["args"]
-
-
-def test_find_arguments_with_array():
-    text = '{"name": "add_items", "arguments": {"items": [1, 2, 3], "name": "list"}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "add_items"
-    assert "[1, 2, 3]" in results[0]["args"]
-
-
-def test_find_arguments_with_nested_array_of_objects():
-    text = '{"name": "batch", "arguments": {"rows": [{"id": 1, "val": "a"}, {"id": 2, "val": "b"}]}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert '"rows"' in results[0]["args"]
-    assert '"id": 1' in results[0]["args"]
-
-
-def test_find_arguments_as_string_not_object():
-    text = '{"name": "echo", "arguments": "just a string"}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "echo"
-    assert "just a string" in results[0]["args"]
-
-
-def test_find_arguments_with_unicode():
-    text = (
-        '{"name": "translate", "arguments": {"text": "\u4f60\u597d\uff0c\u4e16\u754c"}}'
-    )
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "translate"
-
-
-def test_find_arguments_with_escaped_quotes():
-    text = '{"name": "format", "arguments": {"template": "he said \\"hello\\""}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert 'he said \\"hello\\"' in results[0]["args"]
-
-
-def test_find_arguments_with_braces_in_string():
-    text = '{"name": "eval", "arguments": {"code": "function(x) { return x + 1; }"}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "eval"
-    assert "function(x) { return x + 1; }" in results[0]["args"]
-
-
-def test_find_many_properties():
-    args = ",".join(f'"{chr(97 + i % 26)}" : {i}' for i in range(20))
-    text = '{"name": "many", "arguments": {' + args + "}}"
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    assert results[0]["name"] == "many"
-
-
-def test_find_empty_arguments():
-    results = _find_tool_calls('{"name": "ping", "arguments": {}}')
-    assert len(results) == 1
-    assert results[0]["name"] == "ping"
-    assert results[0]["args"] == ""
-
-
-def test_find_extracts_correct_arg_start_position():
-    text = '{"name": "f", "arguments": {"x": 1}}'
-    results = _find_tool_calls(text)
-    assert len(results) == 1
-    json_str = text[results[0]["start"] : results[0]["end"]]
-    assert json_str == text
-
-
-@pytest.mark.parametrize(
-    "text,expected_name,expected_complete",
-    [
-        ('{"name": "func", "arguments": {"city"', "func", False),
-        ('{"name": "func", "arguments": {"city": "BJ"}}', "func", None),
-        ("plain text", None, None),
-        ('{"nam', None, None),
-        ('{"name": "deep", "arguments": {"a": {"b": {"c": ', "deep", None),
-        ('{"name": "batch", "arguments": {"items": [1, 2, ', "batch", None),
-    ],
-)
-def test_find_partial_tool_call(text, expected_name, expected_complete):
-    result = _find_partial_tool_call(text)
-    if expected_name is None:
-        assert result is None
-    else:
-        assert result is not None
-        assert result["name"] == expected_name
-        if expected_complete is not None:
-            assert result["complete"] is expected_complete
-
-
-def test_feed_plain_text():
-    parser = SimpleJsonToolParser()
-    deltas = parser.feed("Hello")
-    assert len(deltas) == 1
-    assert deltas[0]["content"] == "Hello"
-
-
-def test_feed_incremental_text():
-    parser = SimpleJsonToolParser()
-    assert parser.feed("He") == [{"content": "He"}]
-    assert parser.feed("Hello") == [{"content": "llo"}]
-
-
-def test_feed_tool_call_name_delta():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "get_weather", "arguments": {"city": "Beijing"}}'
-    deltas = parser.feed(text)
-    tc_deltas = [d for d in deltas if "tool_calls" in d]
-    assert len(tc_deltas) >= 1
-    name_delta = tc_deltas[0]["tool_calls"][0]
-    assert name_delta["function"]["name"] == "get_weather"
-    assert name_delta["type"] == "function"
-    assert "id" in name_delta
-
-
-def test_feed_tool_call_args_streaming():
-    parser = SimpleJsonToolParser()
-    d1 = parser.feed('{"name": "f", "arguments": {"x":')
-    d2 = parser.feed('{"name": "f", "arguments": {"x": "1"}}')
-    args_deltas = [
-        d
-        for batch in (d1, d2)
-        for d in batch
-        if "tool_calls" in d
-        and "function" in d["tool_calls"][0]
-        and "arguments" in d["tool_calls"][0]["function"]
-    ]
-    assert len(args_deltas) >= 1
-
-
-def test_feed_text_before_tool_call():
-    parser = SimpleJsonToolParser()
-    text = 'Let me check. {"name": "func", "arguments": {"a": 1}}'
-    deltas = parser.feed(text)
-    content_deltas = [d for d in deltas if "content" in d]
-    assert any("Let me check" in d.get("content", "") for d in content_deltas)
-
-
-def test_has_tool_calls_false_by_default():
-    assert SimpleJsonToolParser().has_tool_calls is False
-
-
-def test_has_tool_calls_true_after_detection():
-    parser = SimpleJsonToolParser()
-    parser.feed('{"name": "f", "arguments": {}}')
-    assert parser.has_tool_calls is True
-
-
-def test_feed_no_content_when_no_new_text():
-    parser = SimpleJsonToolParser()
-    parser.feed("Hello")
-    assert parser.feed("Hello") == []
-
-
-def test_feed_multiple_tool_calls():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "f1", "arguments": {"a": 1}}{"name": "f2", "arguments": {"b": 2}}'
-    deltas = parser.feed(text)
-    tc_deltas = [d for d in deltas if "tool_calls" in d]
-    names = set()
-    for batch in tc_deltas:
-        for tc in batch["tool_calls"]:
-            if "function" in tc and "name" in tc["function"]:
-                names.add(tc["function"]["name"])
-    assert "f1" in names
-    assert "f2" in names
-
-
-def test_feed_with_tools_constructor():
-    tools = [{"type": "function", "function": {"name": "get_weather"}}]
-    parser = SimpleJsonToolParser(tools=tools, tool_choice="auto")
-    deltas = parser.feed('{"name": "get_weather", "arguments": {"city": "BJ"}}')
-    assert len(deltas) > 0
-
-
-def test_feed_content_after_tool_call_is_not_emitted():
-    parser = SimpleJsonToolParser()
-    parser.feed('{"name": "f", "arguments": {}} trailing text')
-    assert parser.has_tool_calls
-
-
-def _simulate_streaming(parser, text):
-    all_delta_names = []
-    all_args_chunks = []
-    for i in range(1, len(text) + 1):
-        deltas = parser.feed(text[:i])
-        for d in deltas:
-            if "tool_calls" in d:
-                for tc in d["tool_calls"]:
-                    fn = tc.get("function", {})
-                    if "name" in fn:
-                        all_delta_names.append(fn["name"])
-                    if "arguments" in fn and fn["arguments"]:
-                        all_args_chunks.append(fn["arguments"])
-    return all_delta_names, all_args_chunks
-
-
-def test_streaming_token_by_token_full_build():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "get_weather", "arguments": {"city": "Beijing"}}'
-    names, args_chunks = _simulate_streaming(parser, text)
-    assert "get_weather" in names
-    joined_args = "".join(args_chunks)
-    assert '"city"' in joined_args
-    assert "Beijing" in joined_args
-
-
-def test_streaming_token_by_token_text_then_tool():
-    parser = SimpleJsonToolParser()
-    parts = [
-        "I'll ",
-        "check ",
-        "that. ",
-        '{"',
-        'name": "search", ',
-        '"arguments": {"q": "hello"}}',
-    ]
-    body = ""
-    content_chunks = []
-    tool_names = []
-    for part in parts:
-        body += part
-        deltas = parser.feed(body)
-        for d in deltas:
-            if "content" in d:
-                content_chunks.append(d["content"])
-            if "tool_calls" in d:
-                for tc in d["tool_calls"]:
-                    fn = tc.get("function", {})
-                    if "name" in fn:
-                        tool_names.append(fn["name"])
-    full_content = "".join(content_chunks)
-    assert "I'll check that." in full_content
-    assert "search" in tool_names
-
-
-def test_streaming_multiple_tool_calls_incremental():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "f1", "arguments": {"a": 1}}{"name": "f2", "arguments": {"b": 2}}'
-    names, _ = _simulate_streaming(parser, text)
-    assert names[0] == "f1"
-    assert "f2" in names
-
-
-def test_streaming_deeply_nested_args():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "deep", "arguments": {"a": {"b": {"c": 42}}}}'
-    _, args_chunks = _simulate_streaming(parser, text)
-    joined = "".join(args_chunks)
-    assert '"c": 42' in joined
-
-
-def test_streaming_args_with_unicode():
-    parser = SimpleJsonToolParser()
-    text = (
-        '{"name": "translate", "arguments": {"text": "\u4f60\u597d\uff0c\u4e16\u754c"}}'
-    )
-    _, args_chunks = _simulate_streaming(parser, text)
-    joined = "".join(args_chunks)
-    assert "\u4f60\u597d" in joined
-
-
-def test_streaming_args_with_array():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "add", "arguments": {"items": [1, 2, 3]}}'
-    _, args_chunks = _simulate_streaming(parser, text)
-    joined = "".join(args_chunks)
-    assert "[1, 2, 3]" in joined
-
-
-def test_streaming_empty_arguments():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "ping", "arguments": {}}'
-    deltas = parser.feed(text)
-    tc_deltas = [d for d in deltas if "tool_calls" in d]
-    assert len(tc_deltas) >= 1
-    name_delta = tc_deltas[0]["tool_calls"][0]
-    assert name_delta["function"]["name"] == "ping"
-    assert "arguments" in name_delta["function"]
-
-
-def test_streaming_args_diff_only_emits_new_bytes():
-    parser = SimpleJsonToolParser()
-    step1 = parser.feed('{"name": "f", "arguments": {"city": "Bei')
-    step2 = parser.feed('{"name": "f", "arguments": {"city": "Beijing"}}')
-    all_args = []
-    for step in (step1, step2):
-        for d in step:
-            if "tool_calls" in d:
-                for tc in d["tool_calls"]:
-                    fn = tc.get("function", {})
-                    if "arguments" in fn and fn["arguments"]:
-                        all_args.append(fn["arguments"])
-    joined = "".join(all_args)
-    assert "city" in joined
-    assert "Beijing" in joined
-    assert joined.startswith('"city":')
-    assert all_args[0] != all_args[1]
-
-
-def test_streaming_distinct_tool_call_ids():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "f1", "arguments": {"a": 1}}{"name": "f2", "arguments": {"b": 2}}'
-    all_ids = []
-    for i in range(1, len(text) + 1):
-        deltas = parser.feed(text[:i])
-        for d in deltas:
-            if "tool_calls" in d:
-                for tc in d["tool_calls"]:
-                    if "id" in tc:
-                        all_ids.append(tc["id"])
-    unique = list(dict.fromkeys(all_ids))
-    assert len(unique) == 2
-
-
-def test_parse_complete_basic():
-    parser = SimpleJsonToolParser()
-    body = '{"name": "get_weather", "arguments": {"city": "Beijing"}}'
-    result = parser.parse_complete(body)
-    assert result is not None
-    assert result["tool_calls"][0]["function"]["name"] == "get_weather"
-    assert "Beijing" in result["tool_calls"][0]["function"]["arguments"]
-
-
-def test_parse_complete_no_tool_call():
-    assert SimpleJsonToolParser().parse_complete("Hello world") is None
-
-
-def test_parse_complete_with_content():
-    parser = SimpleJsonToolParser()
-    result = parser.parse_complete('Prefix text. {"name": "f", "arguments": {}}')
-    assert result is not None
-    assert result["content"] == "Prefix text."
-
-
-def test_parse_complete_multiple_tool_calls():
-    parser = SimpleJsonToolParser()
-    body = '{"name": "get_weather", "arguments": {"city": "Beijing"}}{"name": "get_time", "arguments": {"tz": "Asia/Shanghai"}}'
-    result = parser.parse_complete(body)
-    assert result is not None
-    assert len(result["tool_calls"]) == 2
-    assert result["tool_calls"][0]["function"]["name"] == "get_weather"
-    assert result["tool_calls"][1]["function"]["name"] == "get_time"
-
-
-def test_parse_complete_complex_real_world():
-    parser = SimpleJsonToolParser()
-    body = (
-        '{"name": "send_email", "arguments": {'
-        '"to": ["a@b.com", "c@d.com"], "cc": null, '
-        '"subject": "Hello World", "body": "This is a test email.", '
-        '"priority": 1, "attachments": false}}'
-    )
-    result = parser.parse_complete(body)
-    assert result is not None
-    tc = result["tool_calls"][0]
-    assert tc["function"]["name"] == "send_email"
-    args = tc["function"]["arguments"]
-    assert '"to"' in args
-    assert "a@b.com" in args
-    assert "null" in args
-    assert "false" in args
-
-
-def test_parse_complete_content_with_multiple_tool_calls():
-    parser = SimpleJsonToolParser()
-    body = 'I will do two things. {"name": "f1", "arguments": {"a": 1}}{"name": "f2", "arguments": {"b": 2}}'
-    result = parser.parse_complete(body)
-    assert result is not None
-    assert result["content"] == "I will do two things."
-    assert len(result["tool_calls"]) == 2
-
-
-def test_parse_complete_no_arguments_field():
-    parser = SimpleJsonToolParser()
-    result = parser.parse_complete('{"name": "ping"}')
-    assert result is not None
-    assert result["tool_calls"][0]["function"]["name"] == "ping"
-    assert result["tool_calls"][0]["function"]["arguments"] == ""
-
-
-def test_parse_complete_content_is_none_when_pure_tool_call():
-    parser = SimpleJsonToolParser()
-    result = parser.parse_complete('{"name": "f", "arguments": {"x": 1}}')
-    assert result is not None
-    assert result["content"] is None
-
-
-def test_parse_complete_tool_calls_have_ids():
-    parser = SimpleJsonToolParser()
-    result = parser.parse_complete(
-        '{"name": "f1", "arguments": {}}{"name": "f2", "arguments": {}}'
-    )
-    assert result is not None
-    ids = [tc["id"] for tc in result["tool_calls"]]
-    assert len(ids) == 2
-    assert all(isinstance(i, str) and i.startswith("call_") for i in ids)
-    assert ids[0] != ids[1]
-
-
-def test_feed_then_parse_complete_same_instance():
-    parser = SimpleJsonToolParser()
-    parser.feed('{"name": "get_weather", "arguments": {"city": "Beijing"}}')
-    result = parser.parse_complete(
-        '{"name": "get_weather", "arguments": {"city": "Beijing"}}'
-    )
-    assert result is not None
-    assert result["tool_calls"][0]["function"]["name"] == "get_weather"
-    assert parser.has_tool_calls
-
-
-@pytest.mark.parametrize(
-    "text,matches",
-    [
-        ('{"name": "f"}', True),
-        ('{ "name" : "f"}', True),
-        ('{"other": 1}', False),
-        ('prefix {"name": "f", "args": {}}', True),
-        ('{"name": "f"}', True),  # match at start
-        ('   {"name": "f"}', True),
-    ],
-)
-def test_pattern_regex(text, matches):
-    result = _TOOL_CALL_HEAD_RE.search(text)
-    if matches:
-        assert result is not None
-    else:
-        assert result is None
-
-
-def test_pattern_name_at_start():
-    assert _TOOL_CALL_HEAD_RE.match('{"name": "f"}')
-
-
-def test_factory_register_and_create():
-    parser = ToolParserFactory.create("simple_json")
-    assert isinstance(parser, BaseToolParser)
-    assert isinstance(parser, SimpleJsonToolParser)
-
-
-def test_factory_create_passes_tools():
-    parser = ToolParserFactory.create(
-        "simple_json", tools=[{"type": "function"}], tool_choice="required"
-    )
-    assert parser.tool_choice == "required"
-
-
-def test_factory_list_registered():
-    assert "simple_json" in ToolParserFactory.list_registered()
-
-
-def test_factory_create_with_no_extra_kwargs():
-    assert isinstance(ToolParserFactory.create("simple_json"), BaseToolParser)
-
-
-def test_factory_create_with_tools_only():
-    tools = [
-        {
-            "type": "function",
-            "function": {"name": "test", "parameters": {"type": "object"}},
-        }
-    ]
-    parser = ToolParserFactory.create("simple_json", tools=tools)
-    assert parser.tools == tools
-    assert parser.tool_choice == "auto"
-
-
-def test_feed_accepts_token_ids_and_ignores_them():
-    parser = SimpleJsonToolParser()
-    text = '{"name": "get_weather", "arguments": {"city": "Beijing"}}'
-    deltas_with = parser.feed(text, current_token_ids=[123, 456], delta_token_ids=[456])
-    assert len(deltas_with) > 0
-
-
-def test_feed_token_ids_do_not_affect_parsing():
-    parser_no_ids = SimpleJsonToolParser()
-    parser_with_ids = SimpleJsonToolParser()
-    text = '{"name": "get_weather", "arguments": {"city": "Beijing"}}'
-    result_no = parser_no_ids.feed(text)
-    result_with = parser_with_ids.feed(
-        text, current_token_ids=[1, 2, 3], delta_token_ids=[3]
-    )
-    assert len(result_no) == len(result_with)
-    assert (
-        result_no[0]["tool_calls"][0]["function"]["name"]
-        == result_with[0]["tool_calls"][0]["function"]["name"]
-    )
-
-
-def test_parser_uses_token_ids_for_detection():
-    class TokenIdParser(BaseToolParser):
-        def __init__(self, tools=None, tool_choice="auto"):
-            super().__init__(tools, tool_choice)
-            self._detections = 0
-
-        def feed(self, body, current_token_ids=None, delta_token_ids=None):
-            if current_token_ids and 999 in current_token_ids:
-                self._detections += 1
-            return []
-
-        def parse_complete(self, body):
-            return None
-
-        @property
-        def has_tool_calls(self):
-            return self._detections > 0
-
-    parser = TokenIdParser()
-    parser.feed("hello", current_token_ids=[1, 999, 3])
-    assert parser.has_tool_calls
@@ -1,13 +1,6 @@
-import json
-import os
-import tempfile
-
-import pytest
-import safetensors.torch as st
 import torch

 from astrai.config.model_config import EncoderConfig
-from astrai.model.automodel import AutoModel
 from astrai.model.encoder import EmbeddingEncoder

 TINY_CONFIG = dict(
@@ -21,56 +14,92 @@ TINY_CONFIG = dict(
    norm_eps=1e-5,
 )

-_device = "cuda" if torch.cuda.is_available() else "cpu"

-
-def _make_model(**kwargs):
-    config = EncoderConfig(**{**TINY_CONFIG, **kwargs})
-    return EmbeddingEncoder(config).to(device=_device)
-
-
-@pytest.mark.parametrize("pooling_type", ["mean", "cls", "last"])
-def test_encoder_forward_pooling(pooling_type):
-    model = _make_model(pooling_type=pooling_type)
+def test_encoder_forward_mean():
+    config = EncoderConfig(**TINY_CONFIG)
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = EmbeddingEncoder(config).to(device=device)
    model.eval()

    batch_size, seq_len = 2, 8
    input_ids = torch.randint(
-        0, TINY_CONFIG["vocab_size"], (batch_size, seq_len), device=_device
+        0, config.vocab_size, (batch_size, seq_len), device=device
    )

    with torch.no_grad():
        output = model(input_ids)

-    assert output.shape == (batch_size, TINY_CONFIG["dim"])
+    assert output.shape == (batch_size, config.dim)
    assert not torch.isnan(output).any()


-def test_encoder_forward_with_padding():
-    model = _make_model()
+def test_encoder_forward_cls():
+    config = EncoderConfig(**{**TINY_CONFIG, "pooling_type": "cls"})
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = EmbeddingEncoder(config).to(device=device)
    model.eval()

    batch_size, seq_len = 2, 8
    input_ids = torch.randint(
-        0, TINY_CONFIG["vocab_size"], (batch_size, seq_len), device=_device
+        0, config.vocab_size, (batch_size, seq_len), device=device
    )
-    input_mask = torch.ones(batch_size, seq_len, dtype=torch.bool, device=_device)
+
+    with torch.no_grad():
+        output = model(input_ids)
+
+    assert output.shape == (batch_size, config.dim)
+    assert not torch.isnan(output).any()
+
+
+def test_encoder_forward_last():
+    config = EncoderConfig(**{**TINY_CONFIG, "pooling_type": "last"})
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = EmbeddingEncoder(config).to(device=device)
+    model.eval()
+
+    batch_size, seq_len = 2, 8
+    input_ids = torch.randint(
+        0, config.vocab_size, (batch_size, seq_len), device=device
+    )
+
+    with torch.no_grad():
+        output = model(input_ids)
+
+    assert output.shape == (batch_size, config.dim)
+    assert not torch.isnan(output).any()
+
+
+def test_encoder_forward_with_padding():
+    config = EncoderConfig(**TINY_CONFIG)
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = EmbeddingEncoder(config).to(device=device)
+    model.eval()
+
+    batch_size, seq_len = 2, 8
+    input_ids = torch.randint(
+        0, config.vocab_size, (batch_size, seq_len), device=device
+    )
+    input_mask = torch.ones(batch_size, seq_len, dtype=torch.bool, device=device)
    input_mask[:, 4:] = False

    with torch.no_grad():
        output = model(input_ids, input_mask=input_mask)

-    assert output.shape == (batch_size, TINY_CONFIG["dim"])
+    assert output.shape == (batch_size, config.dim)
    assert not torch.isnan(output).any()


 def test_encoder_normalize():
-    model = _make_model(pooling_type="mean", normalize_embeddings=True)
+    config = EncoderConfig(
+        **{**TINY_CONFIG, "pooling_type": "mean", "normalize_embeddings": True}
+    )
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = EmbeddingEncoder(config).to(device=device)
    model.eval()

    batch_size, seq_len = 2, 8
    input_ids = torch.randint(
-        0, TINY_CONFIG["vocab_size"], (batch_size, seq_len), device=_device
+        0, config.vocab_size, (batch_size, seq_len), device=device
    )

    with torch.no_grad():
@@ -81,19 +110,24 @@ def test_encoder_normalize():


 def test_encoder_register():
+    from astrai.model.automodel import AutoModel
+
    assert AutoModel.is_registered("embedding")
    cls = AutoModel.get_component_class("embedding")
    assert cls is EmbeddingEncoder


 def test_encoder_from_transformer_checkpoint():
-    model = _make_model()
+    config = EncoderConfig(**TINY_CONFIG)
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = EmbeddingEncoder(config).to(device=device)
+
    state_dict = model.state_dict()
    state_dict["lm_head.weight"] = torch.randn(
-        TINY_CONFIG["vocab_size"], TINY_CONFIG["dim"], device=_device
+        config.vocab_size, config.dim, device=device
    )

-    new_model = _make_model()
+    new_model = EmbeddingEncoder(config).to(device=device)
    new_model.load_state_dict(state_dict, strict=True)

    for key in model.state_dict():
@@ -101,6 +135,12 @@ def test_encoder_from_transformer_checkpoint():


 def test_encoder_save_load():
+    import json
+    import os
+    import tempfile
+
+    import safetensors.torch as st
+
    test_dir = tempfile.mkdtemp(prefix="encoder_test_")
    config_path = os.path.join(test_dir, "config.json")
    weights_path = os.path.join(test_dir, "model.safetensors")
@@ -1,355 +0,0 @@
-import tempfile
-
-import pytest
-import torch
-
-from astrai.config.model_config import AutoRegressiveLMConfig
-from astrai.model import AutoRegressiveLM
-from astrai.model.components.linear import Linear
-from astrai.model.components.lora import (
-    LoRAConfig,
-    LoRALinear,
-    _collect_lora_info,
-    _get_lora_count,
-    inject_lora,
-    load_lora,
-    merge_lora,
-    save_lora,
-)
-
-MODEL_KWARGS = dict(
-    vocab_size=1000,
-    dim=64,
-    n_heads=4,
-    n_kv_heads=2,
-    dim_ffn=128,
-    n_layers=2,
-    max_len=32,
-    norm_eps=1e-5,
-)
-
-
-def _make_model(**kwargs):
-    kw = {**MODEL_KWARGS, **kwargs}
-    config = AutoRegressiveLMConfig(**kw)
-    model = AutoRegressiveLM(config)
-    model.eval()
-    return model
-
-
-def test_loralinear_init():
-    base = Linear(64, 128)
-    lora = LoRALinear(base, r=8, alpha=16)
-
-    assert lora.weight is base.weight
-    assert not lora.weight.requires_grad
-    assert lora.lora_A.shape == (8, 64)
-    assert lora.lora_B.shape == (128, 8)
-    assert lora.scaling == 2.0
-    assert not lora._merged
-    assert lora.lora_A.requires_grad
-    assert lora.lora_B.requires_grad
-
-
-def test_loralinear_forward_init_zero_delta():
-    base = Linear(4, 4)
-    with torch.no_grad():
-        base.weight.zero_()
-
-    x = torch.randn(2, 4)
-    lora = LoRALinear(base, r=2, alpha=2)
-    base_out = base(x)
-    lora_out = lora(x)
-
-    assert torch.allclose(base_out, lora_out)
-
-
-def test_loralinear_forward_with_delta():
-    base = Linear(4, 4)
-    with torch.no_grad():
-        base.weight.zero_()
-
-    x = torch.randn(2, 4)
-    lora = LoRALinear(base, r=2, alpha=2)
-    base_out = base(x)
-
-    with torch.no_grad():
-        lora.lora_B.fill_(1.0)
-
-    lora_out = lora(x)
-    assert not torch.allclose(base_out, lora_out)
-
-
-def test_loralinear_merge():
-    base = Linear(4, 4)
-    with torch.no_grad():
-        base.weight.zero_()
-
-    x = torch.randn(2, 4)
-    lora = LoRALinear(base, r=2, alpha=2)
-    with torch.no_grad():
-        lora.lora_B.fill_(1.0)
-
-    out_before = lora(x).clone()
-    lora.merge()
-    out_after = lora(x)
-
-    torch.testing.assert_close(out_before, out_after)
-    assert lora._merged
-    assert not hasattr(lora, "lora_A")
-
-
-def test_loralinear_merge_is_idempotent():
-    base = Linear(4, 4)
-    with torch.no_grad():
-        base.weight.zero_()
-
-    lora = LoRALinear(base, r=2, alpha=2)
-    with torch.no_grad():
-        lora.lora_B.fill_(1.0)
-
-    lora.merge()
-    lora.merge()
-
-
-def test_inject_lora_default_target():
-    model = _make_model()
-    n_before = sum(1 for m in model.modules() if isinstance(m, Linear))
-
-    inject_lora(model, r=4, alpha=8)
-
-    lora_count = _get_lora_count(model)
-    assert lora_count > 0
-    assert lora_count < n_before
-
-
-def test_inject_lora_ffn():
-    model = _make_model()
-    from astrai.model.components.lora import TARGET_MODULES_FFN
-
-    inject_lora(model, r=4, alpha=8, target_modules=TARGET_MODULES_FFN)
-    assert _get_lora_count(model) > 0
-
-
-def test_inject_lora_returns_config():
-    model = _make_model()
-    cfg = inject_lora(model, r=8, alpha=32)
-    assert isinstance(cfg, LoRAConfig)
-    assert cfg.r == 8
-    assert cfg.alpha == 32
-
-
-def test_inject_lora_no_matching_targets_warns(caplog):
-    model = _make_model()
-    inject_lora(model, r=4, alpha=8, target_modules={"nonexistent"})
-    assert "No LoRA layers injected" in caplog.text
-
-
-def test_inject_lora_preserves_base_output():
-    model = _make_model()
-    x = torch.randint(0, 1000, (2, 16))
-
-    with torch.no_grad():
-        out_before = model(x)["logits"].clone()
-
-    inject_lora(model, r=4, alpha=8)
-
-    with torch.no_grad():
-        out_after = model(x)["logits"]
-
-    torch.testing.assert_close(out_before, out_after)
-
-
-def test_inject_lora_does_not_reinject():
-    model = _make_model()
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-    first_count = _get_lora_count(model)
-
-    inject_lora(model, r=2, alpha=4, target_modules={"q_proj"})
-    assert _get_lora_count(model) == first_count
-
-
-def test_inject_lora_adds_new_modules():
-    model = _make_model()
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-    first = _get_lora_count(model)
-
-    inject_lora(model, r=4, alpha=8, target_modules={"v_proj"})
-    assert _get_lora_count(model) > first
-
-
-def test_inject_lora_on_mla_model():
-    model = _make_model(
-        attn_type="mla", kv_lora_rank=16, qk_nope_head_dim=16, qk_rope_head_dim=16
-    )
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj", "o_proj"})
-    assert _get_lora_count(model) > 0
-
-
-def test_inject_lora_on_moe_model():
-    model = _make_model(
-        ffn_type="moe",
-        n_routed_experts=4,
-        n_shared_experts=1,
-        n_activated_experts=2,
-        dim_ffn=32,
-    )
-    inject_lora(model, r=4, alpha=8, target_modules={"up", "gate", "down"})
-    assert _get_lora_count(model) > 0
-
-
-def test_state_dict_key_format():
-    model = _make_model()
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-
-    sd = model.state_dict()
-    assert "layers.0.attention.q_proj.weight" in sd
-    assert "layers.0.attention.q_proj.lora_A" in sd
-    assert "layers.0.attention.q_proj.lora_B" in sd
-
-
-def test_only_lora_params_trainable():
-    model = _make_model()
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj", "v_proj"})
-
-    for name, param in model.named_parameters():
-        if isinstance(name.split(".")[-1], str) and "lora" in name:
-            assert param.requires_grad, f"lora param should be trainable: {name}"
-        elif any(name.endswith(f".{t}.weight") for t in ("q_proj", "v_proj")):
-            assert not param.requires_grad, f"injected weight should be frozen: {name}"
-
-
-def test_state_dict_after_inject_consistent_with_original():
-    model = _make_model()
-    sd_before = {k: v for k, v in model.state_dict().items()}
-
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-    sd_after = model.state_dict()
-
-    # original keys unchanged
-    for k in sd_before:
-        assert k in sd_after
-        assert sd_before[k].shape == sd_after[k].shape
-
-    # new lora keys present
-    lora_keys = [k for k in sd_after if "lora" in k]
-    assert len(lora_keys) > 0
-
-
-def test_save_load_roundtrip():
-    model = _make_model()
-    cfg = inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-
-    with torch.no_grad():
-        for m in model.modules():
-            if isinstance(m, LoRALinear):
-                m.lora_B.fill_(0.5)
-
-    x = torch.randint(0, 1000, (2, 16))
-    with torch.no_grad():
-        out_src = model(x)["logits"].clone()
-
-    tmpdir = tempfile.mkdtemp()
-    save_lora(model, tmpdir, cfg)
-
-    model2 = _make_model()
-    model2.load_state_dict(model.state_dict(), strict=False)
-    load_lora(model2, tmpdir)
-
-    with torch.no_grad():
-        out_dst = model2(x)["logits"]
-
-    torch.testing.assert_close(out_src, out_dst)
-
-
-def test_save_after_merge_raises():
-    model = _make_model()
-    cfg = inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-
-    with torch.no_grad():
-        for m in model.modules():
-            if isinstance(m, LoRALinear):
-                m.lora_B.fill_(0.5)
-
-    tmpdir = tempfile.mkdtemp()
-    save_lora(model, tmpdir, cfg)
-    merge_lora(model)
-
-    tmpdir2 = tempfile.mkdtemp()
-    with pytest.raises(RuntimeError, match="No LoRA parameters"):
-        save_lora(model, tmpdir2, cfg)
-
-
-def test_load_lora_on_already_injected():
-    model = _make_model()
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-
-    with torch.no_grad():
-        for m in model.modules():
-            if isinstance(m, LoRALinear):
-                m.lora_B.fill_(0.5)
-
-    tmpdir = tempfile.mkdtemp()
-    save_lora(model, tmpdir, LoRAConfig(r=4, alpha=8, target_modules=("q_proj",)))
-
-    model2 = _make_model()
-    model2.load_state_dict(model.state_dict(), strict=False)
-    inject_lora(model2, r=4, alpha=8, target_modules={"q_proj"})
-
-    # load onto already-injected model
-    load_lora(model2, tmpdir)
-    assert _get_lora_count(model2) > 0
-
-
-def test_load_lora_mismatched_r_raises():
-    model = _make_model()
-    cfg = inject_lora(model, r=8, alpha=16, target_modules={"q_proj"})
-
-    with torch.no_grad():
-        for m in model.modules():
-            if isinstance(m, LoRALinear):
-                m.lora_B.fill_(0.5)
-
-    tmpdir = tempfile.mkdtemp()
-    save_lora(model, tmpdir, cfg)
-
-    model2 = _make_model()
-    model2.load_state_dict(model.state_dict(), strict=False)
-    inject_lora(model2, r=4, alpha=8, target_modules={"q_proj"})
-
-    with pytest.raises(RuntimeError, match="size mismatch"):
-        load_lora(model2, tmpdir)  # strict=False, only lora keys
-
-
-def test_merge_preserves_output():
-    model = _make_model()
-    inject_lora(model, r=4, alpha=8, target_modules={"q_proj"})
-
-    with torch.no_grad():
-        for m in model.modules():
-            if isinstance(m, LoRALinear):
-                m.lora_B.fill_(0.5)
-
-    x = torch.randint(0, 1000, (2, 16))
-    with torch.no_grad():
-        out_before = model(x)["logits"].clone()
-
-    merge_lora(model)
-
-    with torch.no_grad():
-        out_after = model(x)["logits"]
-    torch.testing.assert_close(out_before, out_after)
-
-
-def test_merge_no_lora_warns(caplog):
-    model = _make_model()
-    merge_lora(model)
-    assert "No LoRA layers to merge" in caplog.text
-
-
-def test_collect_lora_info():
-    model = _make_model()
-    info = _collect_lora_info(model)
-    assert "q_proj" in info
-    assert "o_proj" in info
-    assert "q_proj" in info  # each layer has one
--- a/Show More
+++ b/Show More