README.md

---
language:
- en
- it
license: apache-2.0
tags:
- tokenizer
- bpe
- bilingual
- italian
- english
- quark
model_type: quark
vocab_size: 65536
---

# Quark Tokenizer

Tokenizer BPE byte-level bilingue **EN + IT** sviluppato per la famiglia di modelli **Quark** di [OvercastLab / ThingAI](https://huggingface.co/ThingAI).

## Caratteristiche

| Proprietà | Valore |
|---|---|
| Algoritmo | Byte-Level BPE |
| Vocab size | 65.536 (2¹⁶) |
| Lingue | Inglese + Italiano |
| Special tokens | 64 |
| Context length | 2048 (estendibile) |
| Compatibilità | 🤗 `transformers`, `tokenizers` |

# Corpus di addestramento

Il tokenizer è stato addestrato su ~14M righe bilanciate EN/IT (50%/50%) provenienti da:

| Dataset | Lingua | Righe |
|---|---|---|
| Wikipedia EN | EN | 3.000.000 |
| Pile Uncopyrighted | EN | 2.000.000 |
| Falcon RefinedWeb | EN | 2.000.000 |
| Wikipedia IT | IT | 3.000.000 |
| FineWeb-2 (`ita_Latn`) | IT | 2.000.000 |
| MADLAD-400 IT | IT | 1.500.000 |

La parità EN/IT è una scelta deliberata: i tokenizer addestrati prevalentemente su inglese tendono a usare 2–3× più token per rappresentare testi italiani. Questo tokenizer è ottimizzato per entrambe le lingue.

# Special Tokens
```
<unk>          → unknown
<s>            → inizio sequenza (BOS)  — id: 1
</s>           → fine sequenza (EOS)    — id: 2
<pad>          → padding
<|system|>     → turno system
<|user|>       → turno user
<|assistant|>  → turno assistant
<|endofturn|>  → fine turno esplicito
<|thinking|>   → inizio ragionamento (chain-of-thought)
<|/thinking|>  → fine ragionamento
<|reserved_0|> … <|reserved_53|>  → slot riservati (tool use, multimodale, ecc.)
```
Totale: **64 special tokens**

# Chat Template
Il tokenizer include un chat template compatibile con `apply_chat_template`:

```python
from transformers import AutoTokenizer

tok = AutoTokenizer.from_pretrained("ThingAI/QuarkTokenizer")

messages = [
    {"role": "system",    "content": "Sei Quark, un assistente AI creato da OvercastLab."},
    {"role": "user",      "content": "Cos'è la derivata di una funzione?"},
    {"role": "assistant", "content": "La derivata misura la variazione istantanea..."},
]

text = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
print(text)
```

## Uso base
```python
from transformers import AutoTokenizer

tok = AutoTokenizer.from_pretrained("ThingAI/quark-tokenizer")

# Encoding
text = "Il cielo è azzurro e il sole splende."
ids  = tok.encode(text)
print(f"Token: {len(ids)}")   # ~9 token

# Decoding
decoded = tok.decode(ids, skip_special_tokens=True)
print(decoded)

# Batch
batch = tok(["Hello world!", "Ciao mondo!"], padding=True, return_tensors="pt")
```

## Integrazione con modelli Quark

```python
from transformers import AutoTokenizer, AutoModelForCausalLM

tok   = AutoTokenizer.from_pretrained("ThingAI/QuarkTokenizer")
model = AutoModelForCausalLM.from_pretrained("ThingAI/Quark-135M")

inputs = tok("La matematica è", return_tensors="pt")
output = model.generate(**inputs, max_new_tokens=50)
print(tok.decode(output[0], skip_special_tokens=True))
```

## Design Choices
**Perché 65.536?**
È una potenza di 2 (2¹⁶), ottimale per operazioni hardware su GPU/TPU. Più grande di GPT-2 (50.257) e LLaMA-2 (32.000), ma più compatto di LLaMA-3 (128.256). Bilancia efficienza di rappresentazione e dimensione dell'embedding layer.

**Perché Byte-Level BPE?**
Garantisce copertura completa di qualsiasi sequenza UTF-8 senza token `<unk>`. Robustezza su emoji, caratteri accentati italiani (à, è, ì, ò, ù), simboli matematici e codice sorgente.

**Perché 50% italiano?**
I tokenizer standard (GPT-2, LLaMA) sono addestrati su corpus predominantemente inglesi e penalizzano le lingue latine con un overhead di 2–3× nel numero di token. Il bilanciamento 50/50 elimina questa disparità per l'italiano mantenendo piena competenza in inglese.

## Famiglia Quark

| Modello | Parametri | Token pretraining | Stato |
|---|---|---|---|
| Quark-135M v1 | 135M | 15B | ✅ Rilasciato |
| Quark-135M v2 | 135M | 65B | 🔄 In training |

## Licenza

Apache 2.0 — uso libero anche commerciale.

## Citazione
```bibtex
@misc{quark2025,
  title   = {Quark: A Bilingual EN/IT Language Model},
  author  = {OvercastLab / ThingAI},
  year    = {2025},
  url     = {https://huggingface.co/ThingAI/quark-tokenizer}
}
```
---
*Sviluppato da [OvercastLab](https://things-ai.org) · Made in Italy 🇮🇹*