README.md

---
language: en
license: apache-2.0
tags:
  - halo-s
  - language-model
  - sparse-attention
  - causal-lm
  - efficient-transformers
  - gqa
datasets:
  - wikitext
library_name: pyhalos
---

# HALO-S ~50M — WikiText-103 (BPE tiktoken)

Modelo de lenguaje preentrenado con la arquitectura **HALO-S**
(Hierarchical Attention with Local Optimization – Sparse), una alternativa
eficiente al Transformer estándar con complejidad **O(N×K)** en lugar de O(N²).

Entrenado durante **2 épocas** sobre 30M tokens de WikiText-103 con tokenización
BPE (GPT-2 tiktoken, vocab=50257), secuencias de **1024 tokens** y batch efectivo
de 32 (DataParallel en 2× T4, FP16 mixed precision).

## Benchmark: HALO-S vs Transformer Denso

> ⏳ Benchmark en progreso — resultados disponibles próximamente.

| Métrica                        | HALO-S | Transformer |
|-------------------------------|--------|-------------|
| Parámetros                    | —      | —           |
| Val Loss                      | —      | —           |
| Val Perplexity                | —      | —           |
| Latencia forward (1024t, ms)  | —      | —           |
| Pico Memoria GPU (GB)         | —      | —           |
| Tiempo entrenamiento (min)    | —      | —           |

## Uso rápido

```bash
pip install pyhalos safetensors tiktoken
```

```python
import json
import torch
import tiktoken
from safetensors.torch import load_file
from halo.core.config import HaloConfig
from halo.models.halo_model import HaloSModel

# 1. Cargar config
with open("config.json") as f:
    cfg = json.load(f)

config = HaloConfig(
    vocab_size=cfg["vocab_size"],
    hidden_size=cfg["hidden_size"],
    num_layers=cfg["num_layers"],
    num_heads=cfg["num_heads"],
    num_kv_heads=cfg["num_kv_heads"],
    num_globals=cfg["num_globals"],
    local_window=cfg["local_window"],
    dilated_offsets=cfg["dilated_offsets"],
    num_random=cfg["num_random"],
    dropout=0.0,          # 0.0 en inferencia
    use_swiglu=False,
    max_seq_len=cfg["max_seq_len"],
)

# 2. Cargar pesos
model = HaloSModel(config)
state_dict = load_file("model.safetensors")
model.load_state_dict(state_dict)
model.eval()

# 3. Tokenizar y generar
enc = tiktoken.get_encoding("gpt2")
prompt = "The theory of relativity states that"
input_ids = torch.tensor([enc.encode(prompt)]).long()

with torch.no_grad():
    output = model.generate(input_ids, max_new_tokens=100, temperature=0.7, top_k=50)

print(enc.decode(output[0].tolist()))
```

## Arquitectura HALO-S

- **Atención dispersa O(N×K):** neighbor lists en lugar de matrices N×N densas
- **Global Tokens:** `num_globals=2` tokens con atención densa compartida
- **GQA (Grouped Query Attention):** ratio 4:1 (`num_kv_heads=2`) para KV cache compacto
- **Conexiones dilatadas:** `dilated_offsets=[1,2,4,8,16,32,64,128]` para contexto lejano sin costo cuadrático
- **Tokens aleatorios:** `num_random=2` para diversidad en atención
- **RoPE:** Rotary Positional Embeddings

## Entrenamiento

- **Dataset:** WikiText-103 (30M tokens, `wikitext-103-raw-v1`)
- **Tokenizador:** GPT-2 BPE via tiktoken (`vocab_size=50257`)
- **Secuencia:** 1024 tokens
- **Épocas:** 2
- **Precisión:** FP16 mixed precision
- **Hardware:** 2× Tesla T4, DataParallel + gradient accumulation ×4
- **Batch efectivo:** 32
- **Gradient checkpointing:** activado

## Framework

Este modelo requiere [pyhalos](https://github.com/BUEORM/pyhalo) — disponible en PyPI.

## Autor

**BUEORM** — dalusx64@gmail.com