Metadata-Version: 2.4
Name: xlmtec
Version: 3.17.0
Summary: Production-grade LLM fine-tuning framework with CLI
Author: Abdur Rahman
License: MIT
Project-URL: Homepage, https://github.com/Abdur-azure/xlmtec
Project-URL: Documentation, https://Abdur-azure.github.io/xlmtec
Project-URL: Issues, https://github.com/Abdur-azure/xlmtec/issues
Keywords: llm,fine-tuning,lora,qlora,transformers
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: rouge-score>=0.1.2
Requires-Dist: nltk>=3.8.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: huggingface-hub>=0.19.0
Requires-Dist: sentencepiece>=0.1.99
Requires-Dist: protobuf>=3.20.0
Provides-Extra: ml
Requires-Dist: torch>=2.0.0; extra == "ml"
Requires-Dist: transformers>=4.35.0; extra == "ml"
Requires-Dist: datasets>=2.14.0; extra == "ml"
Requires-Dist: peft>=0.7.0; extra == "ml"
Requires-Dist: accelerate>=0.24.0; extra == "ml"
Requires-Dist: bitsandbytes>=0.41.0; extra == "ml"
Provides-Extra: tui
Requires-Dist: textual>=0.52.0; extra == "tui"
Provides-Extra: dpo
Requires-Dist: trl>=0.7.0; extra == "dpo"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.7.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0.0; extra == "docs"
Provides-Extra: claude
Requires-Dist: anthropic>=0.20.0; extra == "claude"
Provides-Extra: gemini
Requires-Dist: google-genai>=0.8.0; extra == "gemini"
Provides-Extra: codex
Requires-Dist: openai>=1.10.0; extra == "codex"
Provides-Extra: ai
Requires-Dist: anthropic>=0.20.0; extra == "ai"
Requires-Dist: google-genai>=0.8.0; extra == "ai"
Requires-Dist: openai>=1.10.0; extra == "ai"
Provides-Extra: full
Requires-Dist: torch>=2.0.0; extra == "full"
Requires-Dist: transformers>=4.35.0; extra == "full"
Requires-Dist: datasets>=2.14.0; extra == "full"
Requires-Dist: peft>=0.7.0; extra == "full"
Requires-Dist: accelerate>=0.24.0; extra == "full"
Requires-Dist: bitsandbytes>=0.41.0; extra == "full"
Requires-Dist: textual>=0.52.0; extra == "full"
Requires-Dist: trl>=0.7.0; extra == "full"
Requires-Dist: pytest>=7.0.0; extra == "full"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "full"
Requires-Dist: pytest-cov>=4.0.0; extra == "full"
Requires-Dist: pytest-timeout>=2.0.0; extra == "full"
Requires-Dist: ruff>=0.1.0; extra == "full"
Requires-Dist: mypy>=1.0.0; extra == "full"
Dynamic: license-file

# xlmtec

**Production-grade LLM fine tuning, distillation, and pruning from the command line.**

[![Deploy](https://github.com/Abdur-azure/xlmtec/actions/workflows/deploy_docs.yml/badge.svg)](https://github.com/Abdur-azure/xlmtec/actions)
[![Stars](https://img.shields.io/github/stars/affaan-m/everything-claude-code?style=flat)](https://github.com/Abdur-azure/xlmtec/stargazers)
[![Forks](https://img.shields.io/github/forks/affaan-m/everything-claude-code?style=flat)](https://github.com/Abdur-azure/xlmtec/network/members)
[![Contributors](https://img.shields.io/github/contributors/affaan-m/everything-claude-code?style=flat)](https://github.com/Abdur-azure/xlmtec/graphs/contributors)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## What it does

`xlmtec` is a modular Python framework for fine-tuning, distilling, and pruning large language models. It wraps HuggingFace Transformers + PEFT in a clean CLI, a validated config system, a composable trainer stack, an interactive TUI, and a full test suite — all CPU-runnable for unit tests.

---

## Install

```bash
git clone https://github.com/Abdur-azure/xlmtec.git
cd xlmtec
pip install -e .
```

---

## 5-minute quickstart

```bash
# 1. Generate sample training data (no network required)
python examples/generate_sample_data.py

# 2. Not sure which method to use? Ask
xlmtec recommend gpt2 --output my_config.yaml

# 3. Train with the generated config
xlmtec train --config my_config.yaml

# 4. Or use a ready-made config
xlmtec train --config examples/configs/lora_gpt2.yaml

# 5. Launch the interactive TUI
xlmtec tui
```

---

## CLI commands

| Command | What it does |
|---------|-------------|
| `xlmtec train` | Fine-tune using a YAML config or inline flags (LoRA / QLoRA / Full / Instruction / DPO / Distillation) |
| `xlmtec evaluate` | Score a saved checkpoint (ROUGE, BLEU, Perplexity) |
| `xlmtec benchmark` | Before/after comparison: base vs fine-tuned |
| `xlmtec merge` | Merge LoRA adapter into base model → standalone model |
| `xlmtec upload` | Push adapter or merged model to HuggingFace Hub |
| `xlmtec recommend` | Inspect model size + VRAM, output optimal YAML config |
| `xlmtec prune` | Structured pruning — zero lowest-magnitude attention heads |
| `xlmtec wanda` | WANDA unstructured pruning — zero weights by \|W\|×activation score |
| `xlmtec tui` | Interactive Textual TUI — all commands via a terminal UI |

---

## Training methods

| Method | Flag | Notes |
|--------|------|-------|
| LoRA | `--method lora` | Default. Adapter-based, memory-efficient |
| QLoRA | `--method qlora` | 4-bit quantised LoRA — large models on limited VRAM |
| Full Fine-Tuning | `--method full_finetuning` | All parameters — small models only |
| Instruction Tuning | `--method instruction_tuning` | Alpaca-style `{instruction, input, response}` data |
| DPO | `--method dpo` | Direct Preference Optimization — requires `pip install trl` |
| Response Distillation | `--method vanilla_distillation` | Student mimics teacher logits (KL + CE loss) |
| Feature Distillation | `--method feature_distillation` | Student mimics teacher hidden states (MSE + KL + CE) |

---

## Pruning commands

```bash
# Structured pruning — zero lowest-magnitude attention heads
xlmtec prune ./outputs/gpt2_lora \
    --output ./outputs/gpt2_pruned \
    --sparsity 0.3 \
    --method heads

# WANDA unstructured pruning — weight × activation scoring, zero-shot
xlmtec wanda ./outputs/gpt2_lora \
    --output ./outputs/gpt2_wanda \
    --sparsity 0.5 \
    --dataset ./data/sample.jsonl
```

---

## Example configs

| Config | Method | Model | Data |
|--------|--------|-------|------|
| `lora_gpt2.yaml` | LoRA | GPT-2 | `data/sample.jsonl` |
| `qlora_llama.yaml` | QLoRA | LLaMA-3.2-1B | HF Hub (needs token) |
| `instruction_tuning.yaml` | Instruction | GPT-2 | `data/instructions.jsonl` |
| `full_finetuning.yaml` | Full | GPT-2 | `data/sample.jsonl` |
| `dpo.yaml` | DPO | GPT-2 | `data/dpo_sample.jsonl` |
| `response_distillation.yaml` | Response Distillation | GPT-2 (student) ← GPT-2-medium | `data/sample.jsonl` |
| `feature_distillation.yaml` | Feature Distillation | GPT-2 (student) ← GPT-2-medium | `data/sample.jsonl` |
| `structured_pruning.yaml` | Structured Pruning | GPT-2 | — |
| `wanda.yaml` | WANDA Pruning | GPT-2 | `data/sample.jsonl` (calibration) |

---

## Python API

```python
from xlmtec.core.config import ConfigBuilder
from xlmtec.core.types import TrainingMethod, DatasetSource
from xlmtec.models.loader import load_model_and_tokenizer
from xlmtec.data import prepare_dataset
from xlmtec.trainers import TrainerFactory

config = (
    ConfigBuilder()
    .with_model("gpt2")
    .with_dataset("./data/sample.jsonl", source=DatasetSource.LOCAL_FILE)
    .with_tokenization(max_length=256)
    .with_training(TrainingMethod.LORA, "./output", num_epochs=3)
    .with_lora(r=8, lora_alpha=16)
    .build()
)

model, tokenizer = load_model_and_tokenizer(config.model.to_config())
dataset = prepare_dataset(config.dataset.to_config(), config.tokenization.to_config(), tokenizer)
result = TrainerFactory.train(
    model, tokenizer, dataset,
    config.training.to_config(),
    config.lora.to_config(),
)
print(f"Done. Loss: {result.train_loss:.4f}  →  {result.output_dir}")
```

---

## Docs

- [Usage Guide](docs/usage.md) — all 9 commands with examples
- [Configuration Reference](docs/configuration.md) — YAML config fields for all methods
- [API Reference](docs/api.md) — Python API for all trainers and pruners
- [TUI Guide](docs/tui.md) — interactive terminal interface
- [Architecture](docs/ARCHITECTURE.md) — module design
- [Contributing](CONTRIBUTING.md) — how to add trainers or commands

---

## Tests

```bash
# Unit tests (no GPU needed)
pytest tests/ -v --ignore=tests/test_integration.py

# Integration tests (CPU ok, ~30s — downloads GPT-2 once)
pytest tests/test_integration.py -v -s

# Full suite
pytest tests/ -v
```

---

## Project status

| Aspect | Status |
|--------|--------|
| Version | 3.13.0 |
| Tests | 200+ unit + integration, all green |
| CI | pytest on Python 3.10 / 3.11 / 3.12 |
| Platform | Windows / macOS / Linux |
| License | MIT |
