Metadata-Version: 2.4
Name: rwkv7-hf
Version: 0.9.0
Summary: Readable pure-PyTorch Hugging Face reference model and converter for RWKV-7.
Author-email: 123123213weqw <300659282+123123213weqw@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/123123213weqw/hf-adapter
Project-URL: Documentation, https://github.com/123123213weqw/hf-adapter/tree/main/docs
Project-URL: Repository, https://github.com/123123213weqw/hf-adapter
Project-URL: Issues, https://github.com/123123213weqw/hf-adapter/issues
Keywords: rwkv,transformers,huggingface,language-model,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch
Requires-Dist: transformers<6,>=4.48
Requires-Dist: safetensors
Requires-Dist: packaging
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: numpy; extra == "test"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "test"
Provides-Extra: train
Requires-Dist: transformers<6,>=4.56.2; extra == "train"
Requires-Dist: peft<1,>=0.19.1; extra == "train"
Requires-Dist: accelerate; extra == "train"
Requires-Dist: datasets<6,>=4.7; extra == "train"
Requires-Dist: trl==0.20.0; extra == "train"
Requires-Dist: wandb<1,>=0.18; extra == "train"
Dynamic: license-file

# RWKV-7 Hugging Face Reference

[English](README.md) | [中文](README_ZH.md)

A readable, pure-PyTorch RWKV-7 implementation for Hugging Face Transformers.
Version 0.9 makes compatibility and reproducibility the default: the model
architecture is visible in one `modeling_rwkv7.py`, recurrent math has one
small boundary in `ops_rwkv7.py`, and each converted model is self-contained.
Optional CUDA Graph and Triton work remains on
`perf/optional-native-backend-v0.10`; older CUDA/JIT/quantization and KV-v2
experiments remain archived on `perf/native-kernels-v0.8`. Neither performance
branch is part of this reference line.

## Install and use a published model

```bash
python -m pip install "torch" "transformers>=4.48,<6"
```

Install the PyTorch build that matches the GPU before installing the adapter.
In particular, current default CUDA 13 wheels may omit `sm_70`; V100 users
should select a compatible CUDA 12.x wheel from the official PyTorch index.
Once PyTorch is present, `pip install rwkv7-hf==0.9.0` keeps that installation.

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "wangyue114514/rwkv7-g1d-0.1b-hf"
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    trust_remote_code=True,
    torch_dtype=torch.float16,
).cuda().eval()

inputs = tokenizer("User: Hello! Assistant:", return_tensors="pt").to("cuda")
with torch.inference_mode():
    output = model.generate(**inputs, max_new_tokens=32)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

The model repository contains its configuration, cache, PyTorch operator,
modeling code, tokenizer, vocabulary, and safetensors. Loading it does not
require `rwkv7-hf`, FLA, Triton, a compiler, or a kernel wheel.

## Convert an official checkpoint

```bash
python -m pip install "torch"  # choose the wheel for your CUDA/GPU first
python -m pip install "rwkv7-hf==0.9.0"
rwkv7-hf convert \
  --input /path/to/model.pth \
  --output ./rwkv7-model-hf \
  --vocab-file /path/to/rwkv_vocab_v20230424.txt \
  --precision fp16 \
  --adapter-layout reference \
  --no-fuse-norm \
  --low-memory
```

`reference` is the default. `thin` remains only as a legacy package-backed
layout for older deployment workflows.

## Public architecture

- `RWKV7Config` with `model_type = "rwkv7"`
- `RWKV7Cache`: canonical `[B,H,K,V]` state plus TMix/CMix shifts
- `RWKV7TimeMix`, `RWKV7ChannelMix`, `RWKV7Block`
- `RWKV7PreTrainedModel`, `RWKV7Model`, `RWKV7ForCausalLM`
- standard loss, cache, generation, save/reload, gradient checkpointing, PEFT
  and Trainer/TRL surfaces

Historical `NativeRWKV7*` class names are 0.9 compatibility aliases.

## Reproduction

- [Architecture](docs/ARCHITECTURE.md)
- [Conversion](docs/CONVERSION.md)
- [Evaluation](docs/EVALUATION.md)
- [LoRA SFT, DPO, and GRPO](docs/FINETUNING.md)
- [Reproducibility artifacts](docs/REPRODUCIBILITY.md)
- [Published models](docs/PUBLISHED_MODELS.md)

```bash
python -m pip install -e ".[test]"
python -m pytest -q
```
