Metadata-Version: 2.4
Name: morphoformer
Version: 3.1.0
Summary: MorphFormer: multilingual morphological reinflection with character-level Transformer (GQA, RoPE, SwiGLU, language adapters)
Author: F000NK, Voluntas Progressus
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: chartoken-vp>=1.1.0
Requires-Dist: torchblocks-vp>=1.1.0
Requires-Dist: sigmorphon-vp>=1.1.0
Requires-Dist: trainkit-vp>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# MorphFormer

Character-level Transformer for multilingual morphological reinflection.

Version 3.1 — modular multi-package architecture by Voluntas Progressus.

## Installation

```bash
pip install morphoformer
```

Requires Python >= 3.14 and PyTorch >= 2.0.

Dependencies are installed automatically:
- `chartoken-vp` — character-level tokenizer
- `torchblocks-vp` — pluggable Transformer blocks
- `sigmorphon-vp` — SigMorphon dataset tools
- `trainkit-vp` — training utilities

## Quick Start

```bash
# Download SigMorphon data
morphoformer download --lang rus,deu,fra --merge

# Train with preset
morphoformer train --preset medium --data "data/collections/*_train.tsv" --device cuda

# Single-word inference
morphoformer infer --checkpoint checkpoints/morph_v3.pt --word "laufen" --morph "V;IND;PST;3;SG" --lang deu

# Interactive REPL
morphoformer serve --checkpoint checkpoints/morph_v3.pt
```

## Architecture

| Component | Implementation |
|---|---|
| Attention | Grouped Query Attention (GQA) with KV cache |
| Positions | Rotary Position Embeddings (RoPE) |
| Feed-forward | SwiGLU |
| Normalization | RMSNorm (pre-norm) |
| Encoder conv | Conformer-style depthwise separable conv1d |
| Adapters | Language-conditioned bottleneck adapters |
| Morph features | Pooled or attention-based structured encoder |

## Presets

| Preset | d_model | Encoder | Decoder | ~Params | VRAM |
|---|---|---|---|---|---|
| small | 384 | 4 layers | 3 layers | ~7M | < 4 GB |
| medium | 512 | 8 layers | 6 layers | ~45M | 4-8 GB |
| large | 768 | 10 layers | 8 layers | ~120M | >= 8 GB |

## CLI Commands

| Command | Description |
|---|---|
| `train` | Train model from TSV data |
| `infer` | Single-word inference |
| `serve` | Interactive REPL |
| `download` | Download SigMorphon 2021 datasets |
| `modules` | List registered NN building blocks |
| `init-config` | Generate TOML config template |

## Data Format

TSV with columns: `lemma`, `features`, `surface_form`, `language`

```
laufen	V;IND;PST;3;SG	lief	deu
```

## Python API

```python
import torch
from chartoken import CharVocab, FeatureVocab
from morphoformer.model import MorphFormer
from morphoformer.inference import greedy_decode

checkpoint = torch.load("checkpoints/morph_v3.pt", map_location="cpu", weights_only=False)
char_vocab = CharVocab.from_dict(checkpoint["char_vocab"])
feature_vocab = FeatureVocab.from_dict(checkpoint["feature_vocab"])
lang_to_id = checkpoint["lang_to_id"]

# Build model, load state_dict, call greedy_decode()
```

## Supported Devices

| Device | Flag |
|---|---|
| Auto-detect | `--device auto` |
| NVIDIA GPU | `--device cuda` |
| AMD GPU | `--device rocm` |
| Intel Arc | `--device xpu` |
| Apple Silicon | `--device mps` |
| CPU | `--device cpu` |

## License

MIT
