HSAQ: documentación limpia (Qué es/Qué NO es, HSAQ v2 aparte) + implementación + scripts abliteración

HSAQ.md

@@ -0,0 +1,154 @@
+# HSAQ — Qué es y cómo funciona
+
+**Hyper Sparse Adaptive Quantization** — documento maestro (v2.0, 2026).
+
+Definición y mecanismo ordenados a partir de la charla del autor en el
+**I Congreso IA-LATAM 2026** (presentación oficial + transcripción del video,
+sintetizada en el whitepaper de Comunidad IA LATAM).
+
+> 🎬 **Charla en YouTube** (caso de uso práctico con Noctua-C y Antigravity):
+> https://www.youtube.com/watch?v=azJURypb3xo
+>
+> 📄 **Whitepaper oficial del congreso**:
+> https://comunidadialatam.org/blog/materia-hsaq-ciberseguridad
+
+---
+
+## 1. ¿Qué es HSAQ?
+
+**HSAQ es un mecanismo de cuantización y poda adaptativa por activaciones.**
+Se integra en la arquitectura del modelo y **silencia la información que no le
+sirve al modelo para entrenarse**.
+
+- Es un **cuantizador/podador adaptativo** inspirado en la **poda sináptica del
+  cerebro humano**: no procesarlo todo, sino *aprender qué cortar*.
+- La clave frente a esquemas de cuantización fija (INT8/INT4/GPTQ/AWQ): las
+  máscaras de HSAQ son **aprendibles** — el sistema *aprende cuándo cortar y
+  cuándo no*.
+- **No es cuantización de pesos estática.** Opera sobre **activaciones**, con
+  umbral recalculado por lote.
+
+---
+
+## 2. El problema que resuelve
+
+Tres cuellos de botella de los Transformers (motivación de la charla):
+
+1. **Atención intratable** en secuencias largas — el cómputo crece y degrada la
+   tarea; las mitigaciones actuales son "un parche, no la solución".
+2. **Pesos estáticos** — un Transformer entrenado no modula ni adapta
+   dinámicamente su procesamiento.
+3. **Desperdicio de memoria en optimizadores** — AdamW usa 2 estados por
+   parámetro (8 bytes), agravando el costo del hardware.
+
+Motivación de fondo: **reducir la VRAM necesaria** para que la IA sea accesible
+"desde los civiles hasta los gobiernos" — entrenar un modelo de 1.33B con
+**10 GB de VRAM en vez de 25**.
+
+---
+
+## 3. ¿Cómo funciona? (tres pilares)
+
+### 3.1 Umbral dinámico por lote
+
+En cada lote se calcula un umbral adaptativo de la activación (kthvalue/mediana)
+y se **silencian las activaciones inactivas** por debajo del umbral.
+
+```
+1. flat   = |x|.view(B, -1)        # magnitudes por batch
+2. n      = flat.size(1)           # total de neuronas
+3. k      = n × (1 - sparsity)     # neuronas a mantener
+4. umbral = kthvalue(flat, k)      # umbral adaptativo por batch
+5. mask   = |x| >= umbral          # máscara binaria {0, 1}
+6. return x * mask                 # neuronas irrelevantes → 0
+```
+
+### 3.2 Gradiente STE
+
+La actualización de pesos **atraviesa la máscara** en retropropagación
+(Straight-Through Estimator): las neuronas activas reciben gradiente, las
+inactivas no — el umbral y la poda se vuelven **entrenables** (autorregulados).
+
+### 3.3 Optimización de VRAM
+
+Reemplaza AdamW por **SGD Nesterov con máscaras adaptativas**: 1 estado por
+parámetro (4 bytes) en vez de 8.
+
+---
+
+## 4. Resultados reportados (prototipo M.A.T.E.R.I.A. v4, 1.33B, BPE)
+
+| Criterio | AdamW (estándar) | HSAQ + SGD Nesterov | Beneficio |
+|---|---|---|---|
+| Memoria del optimizador | 8 bytes/parám | 4 bytes/parám | **50% menos** |
+| VRAM de entrenamiento | 24.8 GB | 10.07 GB | **−14.7 GB (−59.4%)** |
+| Sparsity de activaciones | 0% (densa) | 30% autorregulada | Menos cómputo |
+| Convergencia JEPA | N/A | Loss 1.08 → 0.006 | **−99.3%** |
+
+La curva de sparsity se **autorreguló** en torno a un objetivo calibrado (~0.047),
+lo que demuestra la estabilidad de la poda adaptativa a esa escala — el beneficio
+crece con modelos más grandes.
+
+---
+
+## 5. Aplicación: abliteración selectiva (nuevo, 2026)
+
+Validado con **Qwen3.5-9B**:
+
+1. Se recolecta el vector de refusal por capa: `r = normalize(mean(harmful) − mean(harmless))`.
+2. HSAQ enmascara `r` conservando solo el top (1−sparsity) de componentes
+   (`sparsity=0.3` → retiene 70% del vector).
+3. Los pesos de la capa (`out_proj` + `down_proj`) se ortogonalizan contra el
+   vector enmascarado: `W ← W − r̂ ⊗ (r̂ᵀ W)`.
+
+Resultado: el modelo responde a prompts de seguridad ofensiva **sin degradar
+tareas harmless**; exportado a **GGUF Q4_K_M** (19.3 GB bf16 → ~5.6 GB).
+Modelo: `MethodWhite/Qwen3.5-9B-Abliterated-HSAQ`.
+
+La abliteración clásica borra el vector completo (pierde inteligencia); HSAQ
+elimina solo los componentes ruidosos → **menos pérdida de capacidad**.
+
+---
+
+## 6. Ecosistema de la charla
+
+- **M.A.T.E.R.I.A.** — *Multi-Agentic Toroidal Engine for Recursive Intelligent
+  Analysis*: motor multiagente con HUB central y ranuras de agentes sobre
+  contexto compartido y persistente, arquitectura anidable.
+- **HSAQ** — cuantización/poda adaptativa por activaciones (este documento).
+- **Noctua-C** — framework de ingeniería inversa (80+ módulos, sandbox) operado
+  por un agente de IA; demo en vivo en la charla.
+
+---
+
+## 7. Limitaciones y roadmap
+
+| Limitación | Plan |
+|---|---|
+| Sparsity objetivo calibrado (no fijo por capa) | Sparsity configurable/aprendida por capa |
+| `x * mask` no ahorra FLOPs reales sin kernel sparse | Kernel CUDA sparse |
+| `kthvalue` fuera de opset ONNX | Wrapper con `topk` |
+| Aplicar HSAQ en runtime dentro de llama.cpp/GGUF | Bloque/máscara en el motor |
+
+Roadmap: primer prototipo 2026 ✓ → modelos comerciales 2027 → gobiernos/empresas
+2028 → seguir reduciendo consumo de cómputo 2029.
+
+---
+
+## 8. Evidencia
+
+- Implementación: `hsaq.py` (`nn.Module`, 64 líneas).
+- Estándar: `HSAQ_STANDARD.md` (v1.0).
+- Paper: `PAPER_CIENTIFICO_MATERIA_V4.md`.
+- Scripts: `abliterate_hsaq.py`, `measure_vram.py`.
+- Whitepaper congreso: https://comunidadialatam.org/blog/materia-hsaq-ciberseguridad
+
+---
+
+## 9. Créditos
+
+Desarrollado por **Jesús Antonio Zárate Hernández** (MethodWhite, Chile) —
+Ingeniero en Ciberseguridad, creador de M.A.T.E.R.I.A. y HSAQ.
+Charla: I Congreso IA-LATAM 2026 · [LinkedIn](https://www.linkedin.com/in/methodwhite)
+
+Si te sirve, invítame un café ☕ → **https://buymeacoffee.com/methodwhite**

HSAQ_DOCUMENTACION_DETALLADA.md

@@ -0,0 +1,319 @@
+# HSAQ — HyperSparse Adaptive Quantization
+
+## Documentación Técnica Detallada para Conferencia
+
+---
+
+> ## ¿Qué es? ✅
+> Cuantización y poda adaptativa de **activaciones** (máscara binaria dinámica
+> por `kthvalue`, umbral por lote, máscaras aprendibles, gradiente STE,
+> SGD Nesterov a 4 bytes/parám).
+>
+> ## ¿Qué NO es? ❌
+> **No es cuantización de pesos.** No es INT8, INT4, GPTQ, AWQ ni bitsandbytes.
+> No opera sobre pesos — opera exclusivamente sobre activaciones.
+>
+> ## HSAQ v2 — aparte ⚠️
+> La cuantización de pesos INT8/INT4 descrita en el paper de M.A.T.E.R.I.A. V4
+> es una **extensión experimental separada**; no forma parte de esta definición.
+
+---
+
+## 1. Definición
+
+**HSAQ** (HyperSparse Adaptive Quantization) es una técnica de ejecución dispersa adaptativa que reduce el costo computacional de redes neuronales activando selectivamente solo las neuronas más relevantes durante cada forward pass.
+
+A diferencia de la cuantización tradicional (que reduce la precisión de los pesos), HSAQ **selecciona dinámicamente qué neuronas se ejecutan**, creando una máscara de dispersidad que se recalcula en cada batch.
+
+---
+
+## 2. Problema que Resuelve
+
+### 2.1 El Problema de la Redundancia Neural
+
+En una red neuronal estándar, **todas las neuronas se ejecutan** en cada forward pass, independientemente de su relevancia para la entrada actual. Esto genera:
+
+- **Ineficiencia computacional**: ~30-50% de las neuronas producen activaciones cercanas a cero
+- **Consumo energético innecesario**: Cada multiplicación matriz-vector cuesta energía
+- **Latencia innecesaria**: Tiempo de cómputo desperdiciado en cálculos irrelevantes
+
+### 2.2 Solución de HSAQ
+
+HSAQ identifica y **enmascara** las neuronas menos relevantes en tiempo real, reduciendo el cómputo sin pérdida de precisión.
+
+---
+
+## 3. Algoritmo
+
+### 3.1 Pseudocódigo
+
+```
+ENTRADA: tensor x de forma [B, T, D]
+PARÁMETRO: sparsity ∈ [0, 1] (fracción de neuronas a enmascarar)
+
+1. flat = |x|.reshape(B, T*D)           # Aplanar y tomar magnitudes
+2. n = T * D                             # Total de dimensiones
+3. k = n * (1 - sparsity)                # Número de neuronas a MANTENER
+4. thresh = kthvalue(flat, k, dim=1)     # Umbral dinámico por batch
+5. mask = |x| >= thresh                  # Máscara booleana
+6. SALIDA: x * mask                      # Solo neuronas relevantes pasan
+```
+
+### 3.2 Explicación Paso a Paso
+
+| Paso | Operación | Propósito |
+|------|-----------|-----------|
+| 1 | `flat = |x|.reshape(B, -1)` | Obtener magnitudes de todas las activaciones |
+| 2 | `k = n * (1 - sparsity)` | Calcular cuántas neuronas conservar (ej: sparsity=0.3 → k=70% de n) |
+| 3 | `thresh = kthvalue(flat, k)` | Encontrar el valor que separa el top-70% del bottom-30% |
+| 4 | `mask = |x| >= thresh` | Crear máscara: True donde la activación supera el umbral |
+| 5 | `x * mask` | Enmascarar activaciones irrelevantes (→ 0) |
+
+### 3.3 Ejemplo Visual
+
+```
+Entrada x:          [0.8, -0.1, 0.5, -0.02, 0.9, 0.01]
+Magnitudes:         [0.8,  0.1, 0.5,  0.02, 0.9, 0.01]
+sparsity = 0.5      → conservar top-50% (3 de 6 valores)
+
+kthvalue([0.8, 0.1, 0.5, 0.02, 0.9, 0.01], k=3) = 0.5
+thresh = 0.5
+
+mask:               [True, False, True, False, True, False]
+Salida:             [0.8,   0,   0.5,    0,   0.9,    0]
+```
+
+---
+
+## 4. Propiedades Clave
+
+### 4.1 Adaptativo por Batch
+
+El umbral `thresh` se recalcula **en cada batch** usando `kthvalue`. Esto significa:
+
+- **No hay umbral fijo**: A diferencia de técnicas como "activaciones > 0.01", HSAQ se adapta a la distribución de cada batch
+- **Robusto a cambios de escala**: Si las activaciones crecen o decrcen, el umbral se ajusta automáticamente
+- **Preserva la estructura relativa**: Siempre conserva el top-X% por magnitud, no por valor absoluto
+
+### 4.2 Gradiente Fluid
+
+La máscara binaria es **diferenciable** en la práctica (el gradiente fluye a través de las activaciones no enmascaradas). Esto permite:
+
+- **Entrenamiento end-to-end**: HSAQ se integra en el graph de cómputo
+- **Aprendizaje de sparsity**: El modelo puede aprender a producir activaciones más concentradas
+- **Combinación con other QAT techniques**: Complementa cuantización de pesos y activaciones
+
+### 4.3 Agonístico de Hardware
+
+HSAQ implementa la operación usando solo:
+- `torch.abs()` → soportado en CPU, GPU, TPU
+- `.reshape()` → universal
+- `torch.kthvalue()` → implementado en todos los backends
+- Element-wise multiplication → universal
+
+**No requiere**: Tensor Cores, CUDA kernels custom, instrucciones SIMD específicas.
+
+---
+
+## 5. Comparación con Técnicas Relacionadas
+
+### 5.1 HSAQ vs Cuantización Tradicional (INT8/INT4)
+
+| Aspecto | Cuantización (INT8) | HSAQ |
+|---------|---------------------|------|
+| Qué reduce | Precisión de pesos (32→8 bits) | Número de neuronas activas |
+| Cuándo se aplica | Post-entrenamiento o QAT | Durante inference (y training) |
+| Pérdida de precisión | Sí (quantization error) | Mínima (soloactivaciones ~0) |
+| Adaptabilidad | Fija (mismo esquema para todas las entradas) | Dinámica (cambia por batch) |
+| Hardware requerido | Soporte INT8 en hardware | Cualquier hardware |
+
+### 5.2 HSAQ vs Pruning (Static)
+
+| Aspecto | Pruning Estático | HSAQ |
+|---------|------------------|------|
+| Qué elimina | Pesos/estructura del modelo | Activaciones por batch |
+| Cuándo | Post-entrenamiento | Cada forward pass |
+| Reentrenamiento | Requiere fine-tuning | No requiere |
+| Adaptabilidad | No cambia después de pruning | Se adapta a cada entrada |
+
+### 5.3 HSAQ vs Google TurboQuant
+
+| Aspecto | Google TurboQuant | HSAQ |
+|---------|-------------------|------|
+| Enfoque | Cuantización fija post-entrenamiento | Ejecución dispersa adaptativa |
+| Granularidad | Por tensor (pesos) | Por elemento (activaciones) |
+| Adaptabilidad | Ninguna (mismo esquema siempre) | Por batch (umbral dinámico) |
+| Entrenable | No (post-processing) | Sí (gradiente fluye) |
+| Hardware | Requiere soporte INT8 | Funciona en cualquier hardware |
+| Overhead | Requiere calibración | Cero overhead (cálculo inline) |
+
+**Por qué HSAQ supera a TurboQuant:**
+
+1. **Adaptabilidad**: TurboQuant aplica el mismo esquema de cuantización a todas las entradas. HSAQ ajusta el umbral dinámicamente.
+2. **Granularidad**: TurboQuant opera a nivel de tensor (bloques de pesos). HSAQ opera a nivel de elemento (cada activación individual).
+3. **Entrenabilidad**: TurboQuant es post-entrenamiento. HSAQ se integra en el graph de cómputo y puede optimizar su comportamiento.
+4. **Cero overhead**: TurboQuant requiere pasos de calibración. HSAQ calcula el umbral en línea con una sola operación `kthvalue`.
+
+---
+
+## 6. Implementación en M.A.T.E.R.I.A. V3
+
+### 6.1 Código Fuente
+
+```python
+class HSAQ(nn.Module):
+    def __init__(self, sparsity=0.3):
+        super().__init__()
+        self.sparsity = sparsity  # 30% de neuronas enmascaradas
+
+    def forward(self, x):
+        flat = x.abs().view(x.size(0), -1)
+        n = flat.size(1)
+        k = max(1, min(n - 1, int(n * (1 - self.sparsity))))
+        thresh = torch.kthvalue(flat, k, dim=1).values
+        thresh = thresh.view(-1, *([1] * (x.dim() - 1)))
+        mask = x.abs() >= thresh
+        return x * mask
+```
+
+### 6.2 Posición en la Arquitectura
+
+```
+Input tokens
+    ↓
+Token Embedding (vocab → 256 dims)
+    ↓
+╔══════════════════════════════╗
+║  HSAQ Sparse Execution      ║  ← Aquí se enmascaran el 30% de neuronas
+║  (sparsity=0.3)             ║
+╚══════════════════════════════╝
+    ↓
+Transformer Blocks (GQA + RoPE + SwiGLU) × 3 capas
+    ↓
+Synapsis Memory (128 slots, top-3 retrieval)
+    ↓
+LIF-SNN (neuronas de pulsos)
+    ↓
+SSM (State Space Model)
+    ↓
+JEPA (predictive embeddings)
+    ↓
+RMSNorm → Linear Head → Output logits
+```
+
+### 6.3 Parámetros del Modelo Base
+
+| Parámetro | Valor | Descripción |
+|-----------|-------|-------------|
+| HSAQ sparsity | 0.3 | 30% de neuronas enmascaradas |
+| Hidden dim | 256 | Dimensiones de embedding |
+| Neuronas activas por batch | ~179 de 256 | 70% de 256 = 179.2 |
+| Ahorro computacional | ~30% | En capas lineales subsecuentes |
+
+---
+
+## 7. Resultados Experimentales
+
+### 7.1 Impacto en Accuracy
+
+| Configuración | Val Accuracy | Val Loss | Diferencia |
+|---------------|-------------|----------|------------|
+| Sin HSAQ (sparsity=0) | 98.83% | 0.0363 | baseline |
+| HSAQ (sparsity=0.3) | 98.83% | 0.0363 | +0.00% |
+| HSAQ (sparsity=0.5) | ~98.5% | ~0.040 | -0.3% |
+
+**Conclusión**: Con sparsity=0.3, HSAQ **no reduce accuracy** mientras reduce el cómputo en ~30%.
+
+### 7.2 Impacto en Velocidad
+
+| Operación | Sin HSAQ | Con HSAQ | Speedup |
+|-----------|----------|----------|---------|
+| Forward pass (CPU) | 1.0x | ~0.75x* | ~25% más rápido |
+| Forward pass (GPU) | 1.0x | ~0.80x* | ~20% más rápido |
+
+*El speedup real depende de la implementación del kernel de masking. En PyTorch estándar, el overhead de `kthvalue` compensa parte del ahorro. En implementaciones custom (CUDA kernels), el speedup es mayor.
+
+### 7.3 Spike Rate del SNN
+
+El spike rate de las neuronas LIF se mantiene estable (~0.01-0.05) con y sin HSAQ, indicando que la ejecución dispersa no afecta la dinámica temporal del SNN.
+
+---
+
+## 8. Ventajas para Presentación en Conferencia
+
+### 8.1 Innovación Clave
+
+HSAQ es una **contribución original** de M.A.T.E.R.I.A. que combina:
+- **Sparsity adaptativa** (como Dynamic Sparse Training)
+- **Quantización aware** (como QAT)
+- **Ejecución en línea** (sin post-processing)
+
+### 8.2 Aplicabilidad
+
+HSAQ es especialmente útil para:
+- **Edge devices**: Reducción de cómputo sin pérdida de accuracy
+- **Embedded AI**: Menor consumo energético
+- **Real-time inference**: Latencia reducida
+- **CPU-only training**: Hace viable entrenar en hardware limitado
+
+### 8.3 Comparación con Estado del Arte
+
+| Trabajo | Enfoque | HSAQ vs |
+|---------|---------|---------|
+| SparseGPT (2023) | Pruning post-training | HSAQ es dinámico, no requiere retraining |
+| TurboQuant (Google) | Cuantización INT8 | HSAQ es adaptable por batch |
+| Dynamic Sparse Training | Sparsity durante training | HSAQ funciona también en inference |
+| LLM.int8() | Mixed-precision | HSAQ es más ligero y hardware-agnostic |
+
+---
+
+## 9. Diagrama para Presentación
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  HSAQ - Flujo de Datos                  │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Input: x ∈ ℝ^(B×T×D)                                   │
+│    │                                                    │
+│    ▼                                                    │
+│  ┌─────────────────────┐                                │
+│  │  |x|.reshape(B, -1) │  Magnitudes                    │
+│  └─────────┬───────────┘                                │
+│            │                                            │
+│    ▼       │                                            │
+│  ┌─────────────────────┐                                │
+│  │  k = n × (1 - 0.3)  │  Neuronas a conservar          │
+│  └─────────┬───────────┘                                │
+│            │                                            │
+│    ▼       │                                            │
+│  ┌─────────────────────┐                                │
+│  │  thresh = kthvalue   │  Umbral dinámico              │
+│  └─────────┬───────────┘                                │
+│            │                                            │
+│    ▼       │                                            │
+│  ┌─────────────────────┐                                │
+│  │  mask = |x| >= thresh│  Máscara binaria              │
+│  └─────────┬───────────┘                                │
+│            │                                            │
+│    ▼       │                                            │
+│  ┌─────────────────────┐                                │
+│  │  output = x × mask   │  Solo neuronas relevantes     │
+│  └─────────────────────┘                                │
+│                                                         │
+│  Resultado: 30% de neuronas → 0, 70% pasan sin cambio   │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 10. Referencias
+
+1. M.A.T.E.R.I.A. V3 Paper: `PAPER_CIENTIFICO_MATERIA_V3.md`
+2. Arquitectura técnica: `V3_ARQUITECTURA.md`
+3. Código fuente: `models/core/hsaq.py`
+4. Configuración: `configs/3.8M.yaml`
+
+---
+
+*Documento preparado para presentación en conferencia — Julio 2026*

HSAQ_FORMATO.md

@@ -0,0 +1,222 @@
+# HSAQ — HyperSparse Adaptive Quantization
+
+> ## ¿Qué es? ✅
+> Cuantización y poda adaptativa de **activaciones** (máscara binaria por
+> `kthvalue`, umbral por lote, máscaras aprendibles, STE, SGD Nesterov).
+>
+> ## ¿Qué NO es? ❌
+> No es cuantización de pesos (INT8/INT4/GPTQ/AWQ/bitsandbytes). Opera solo
+> sobre activaciones, no sobre pesos.
+>
+> ## HSAQ v2 — aparte ⚠️
+> Extensión experimental (cuantización de pesos INT8/INT4) del paper de
+> M.A.T.E.R.I.A. V4; separada de esta definición core.
+
+## Definición Formal
+
+HSAQ es un mecanismo de **cuantización de activaciones vía sparsity adaptativa**.
+La "cuantización" refiere a que las activaciones se reducen a {0, valor} mediante
+una máscara binaria dinámica calculada por batch.
+
+**No es cuantización de pesos.** No es INT8/INT4. No es bitsandbytes.
+HSAQ opera exclusivamente sobre **activaciones**, no sobre pesos.
+
+---
+
+## 1. Algoritmo
+
+```
+Entrada: x ∈ ℝ^(B×T×D)  (batch de activaciones)
+Parámetro: sparsity ∈ [0,1)
+
+  flat = |x|.reshape(B, -1)       # Magnitudes por batch
+  n = flat.size(1)                 # Total de neuronas
+  k = n * (1 - sparsity)           # Neuronas a mantener (top-K%)
+  thresh = kthvalue(flat, k)       # Umbral dinámico por batch
+  mask = |x| >= thresh             # Máscara binaria {0, 1}
+  return x * mask                  # ~30% de activaciones → 0
+```
+
+### 1.1 Propiedades clave
+
+| Propiedad | Descripción |
+|-----------|-------------|
+| **Adaptativo** | El umbral `kthvalue` se recalcula en cada batch |
+| **Por elemento** | Cada neurona se evalúa individualmente contra el umbral |
+| **Hardware-agnostic** | Solo usa torch.abs, reshape, kthvalue, multiplicación |
+| **Gradiente fluye** | STE implícito: el gradiente pasa por las neuronas activas |
+| **Sin estado** | No hay buffers persistentes entre batches |
+
+### 1.2 Parámetros
+
+| Parámetro | Default | Función |
+|-----------|---------|---------|
+| `sparsity` | 0.3 | Fracción de activaciones a enmascarar (0.3 = 30%) |
+
+Éste es el **único parámetro** de HSAQ. Todo lo demás (weight_bits, AWQ, etc.)
+son externos y no forman parte del mecanismo central.
+
+---
+
+## 2. HSAQ como Optimizer
+
+HSAQ **reemplaza a AdamW** como mecanismo de optimización.
+
+### 2.1 Por qué funciona
+
+1. La máscara sparse (kthvalue) selecciona las neuronas más activas por batch
+2. El gradiente solo fluye por las neuronas no enmascaradas
+3. Esto crea un **regularización adaptativa**: las neuronas irrelevantes no reciben gradiente
+4. El umbral dinámico evita la necesidad de momentum/estados de optimizer
+
+### 2.2 Optimizer externo
+
+Se usa SGD Nesterov (momentum=0.9) para actualizar pesos:
+
+```
+HSAQ + SGD Nesterov = optimizer completo
+  ├── HSAQ: máscara sparse adaptativa (regularización dinámica)
+  └── SGD: actualización de pesos con momentum
+```
+
+**No se usa AdamW.** SGD con momentum tiene solo 1 estado de optimizer por
+parámetro (vs 2 de AdamW), ahorrando 4 bytes por parámetro.
+
+### 2.3 Hyperparámetros recomendados
+
+| Parámetro | Valor | Razón |
+|-----------|-------|-------|
+| `sparsity` | 0.3 | Balance cómputo/precisión |
+| `lr` | 5e-4 | Tasa de aprendizaje |
+| `momentum` | 0.9 | Nesterov momentum |
+| `weight_decay` | 0.01 | Regularización L2 |
+| `clip_grad_norm` | 1.0 | Estabilidad |
+
+---
+
+## 3. Pipeline de Entrenamiento (con HSAQ por capas)
+
+```
+1. Embedding → HSAQ (sparsity 30%)
+2. Transformer Block 1 → HSAQ (sparsity 30%)   ← umbral propio
+3. Transformer Block 2 → HSAQ (sparsity 30%)   ← umbral propio
+4. Transformer Block N → HSAQ (sparsity 30%)   ← umbral propio
+5. SNN + SSM → JEPA → Head → logits
+```
+
+Cada capa tiene su propio umbral dinámico calculado via kthvalue.
+Esto permite que:
+
+- Capas tempranas (bajo nivel) tengan patrones de activación distintos
+- Capas tardías (alto nivel) se especialicen en representaciones más abstractas
+- El modelo aprenda qué información preservar en cada nivel
+- Diferentes distribuciones de activación por capa no afecten el umbral global
+
+### 3.1 Forward con HSAQ por capas
+
+```
+h = Embedding(x)         # [B, T, dim]
+h = HSAQ(h)               # Sparsity post-embedding
+
+for layer in transformer:
+    h = layer(h)           # Forward del transformer block
+    h = HSAQ(h)            # Sparsity por capa (umbral propio)
+
+h = SNN(h)                 # Neuronas de pulsos
+h = SSM(h)                 # State Space Model
+h = JEPA(h)                # Espacio latente
+h = Head(h)                # Logits finales
+```
+
+```
+1. Forward pass
+   ├── Token Embedding → ℝ^(B×T×D)
+   ├── HSAQ sparsity → 30% de activaciones → 0
+   ├── Transformer Blocks (GQA + RoPE + SwiGLU)
+   ├── LIF-SNN (neuronas de pulsos)
+   ├── SSM (State Space Model)
+   ├── JEPA Encoder → espacio latente
+   └── Head → logits
+
+2. Backward pass
+   └── Gradiente fluye solo por activaciones activas (STE nativo)
+
+3. Weight update
+   └─��� SGD Nesterov (momentum 0.9)
+```
+
+---
+
+## 4. No es HSAQ (cosas que NO pertenecen)
+
+| Componente | Motivo de exclusión |
+|-----------|---------------------|
+| INT8/INT4 weight quantization | HSAQ cuantiza activaciones, no pesos |
+| bitsandbytes 8-bit Adam | HSAQ reemplaza a AdamW |
+| AWQ calibration | Es post-training, no parte de HSAQ |
+| GPTQ | Es compresión de pesos, ortogonal a HSAQ |
+| BPE tokenizer | HSAQ funciona con char-level |
+| Weight tying | Es optimización de arquitectura, no de HSAQ |
+
+---
+
+## 5. Código Mínimo
+
+```python
+class HSAQ(nn.Module):
+    """HyperSparse Adaptive Quantization — sparsity adaptativa"""
+    def __init__(self, sparsity=0.3):
+        super().__init__()
+        self.sparsity = sparsity
+
+    def forward(self, x):
+        flat = x.abs().view(x.size(0), -1)    # Magnitudes
+        k = int(flat.size(1) * (1 - self.sparsity))  # Top-K
+        thresh = torch.kthvalue(flat, k, dim=1).values  # Umbral dinámico
+        thresh = thresh.view(-1, *([1] * (x.dim() - 1)))
+        return x * (x.abs() >= thresh)         # Máscara binaria
+
+# Modo de uso en modelo:
+# h = self.tok_emb(x)
+# h = HSAQ(sparsity=0.3)(h)    ← 30% de activaciones → 0
+# h = transformer(h)           ← gradiente solo fluye por neuronas activas
+```
+
+---
+
+## 6. HSAQ vs TurboQuant (Google)
+
+| Aspecto | TurboQuant (Google) | HSAQ |
+|---------|--------------------|------|
+| **Enfoque** | Cuantización fija post-entrenamiento | Sparsity adaptativa dinámica |
+| **Granularidad** | Por tensor (pesos) | Por elemento (activaciones) |
+| **Umbral** | Fijo (calibrado offline) | Dinámico (kthvalue por batch) |
+| **Hardware** | Requiere soporte INT8 | CPU/GPU/TPU (solo kthvalue) |
+| **Calibración** | Dataset de calibración offline | Zero overhead (inline) |
+| **Adaptabilidad** | Ninguna (mismo esquema siempre) | Por batch (cambia con cada input) |
+| **Permite modelos más grandes** | No (solo comprime) | Sí (sparsity = menos recursos) |
+
+### Por qué HSAQ supera a TurboQuant
+
+1. **No malgasta recursos**: solo las neuronas relevantes se activan por batch
+2. **Modelos más grandes en hardware limitado**: con sparsity=0.3, un modelo 190M
+   corre como si fuera ~133M, permitiendo ejecutar modelos que no cabrían de otra forma
+3. **Adaptativo**: el umbral se ajusta a la entrada, no hay configuración fija
+4. **Sin calibración**: no necesita datasets externos ni pasos post-entrenamiento
+5. **Más eficiente energéticamente**: menos FLOPs = menos consumo
+
+---
+
+## 7. Referencia rápida
+
+| Concepto | Respuesta |
+|----------|-----------|
+| ¿Qué cuantiza? | **Activaciones** (no pesos) |
+| ¿Cómo? | Máscara binaria vía kthvalue |
+| ¿Cada cuánto se recalcula? | **Cada batch** (umbral dinámico) |
+| ¿Qué reemplaza? | **AdamW** como optimizer |
+| ¿Qué optimizer usa? | SGD Nesterov (momentum=0.9) |
+| Parámetros | Solo `sparsity` (default 0.3) |
+| ¿INT8? | NO |
+| ¿bitsandbytes? | NO |
+| ¿BPE? | NO |

HSAQ_STANDARD.md

@@ -0,0 +1,259 @@
+# HSAQ Standard — HyperSparse Adaptive Quantization
+
+## Versión 1.0 — Julio 2026
+
+---
+
+> ## ¿Qué es? ✅
+> Cuantización y poda adaptativa de **activaciones**: máscara binaria dinámica
+> por `kthvalue` (umbral recalculado por lote), máscaras aprendibles, gradiente
+> STE y SGD Nesterov a 4 bytes/parám.
+>
+> ## ¿Qué NO es? ❌
+> **No es cuantización de pesos.** No es INT8, INT4, GPTQ, AWQ ni bitsandbytes.
+> No opera sobre pesos — opera exclusivamente sobre activaciones.
+>
+> ## HSAQ v2 — aparte ⚠️
+> La cuantización de pesos INT8/INT4 del paper de M.A.T.E.R.I.A. V4 es una
+> **extensión experimental separada**; no forma parte de esta definición core.
+
+---
+
+## 1. Definición
+
+HSAQ (HyperSparse Adaptive Quantization) es un mecanismo de **cuantización de activaciones**
+mediante **sparsity adaptativa dinámica**, donde cada capa de la red calcula su propio umbral
+vía `torch.kthvalue` en cada forward pass.
+
+**La "cuantización" en HSAQ** refiere a que las activaciones se reducen a un conjunto
+discreto de valores {0, valor_original} mediante una máscara binaria. NO es cuantización
+de pesos. NO es INT8/INT4. NO es bitsandbytes.
+
+---
+
+## 2. Principios Fundamentales
+
+1. **Adaptativo**: el umbral de sparsity se recalcula en cada batch usando `kthvalue`
+2. **Por capa**: cada componente (embedding, transformer, SNN, SSM, JEPA) tiene su propio umbral
+3. **Sin calibración**: no requiere datasets externos ni pasos post-entrenamiento
+4. **Hardware-agnostic**: funciona en CPU, GPU y TPU sin modificaciones
+5. **Sin estado**: no hay buffers persistentes entre batches
+6. **Gradiente fluye**: las neuronas activas reciben gradiente normalmente (STE nativo)
+
+---
+
+## 3. Algoritmo
+
+### 3.1 Pseudocódigo
+
+```
+Entrada: x ∈ ℝ^(B×T×D)    # Batch de activaciones
+Parámetro: sparsity ∈ [0,1)  # Fracción a enmascarar
+
+1. magnitudes = |x|.view(B, -1)          # Magnitudes por batch
+2. n = magnitudes.size(1)                # Total de neuronas
+3. k = n × (1 - sparsity)               # Neuronas a mantener
+4. umbral = kthvalue(magnitudes, k)      # k-ésimo valor más pequeño
+5. mascara = |x| ≥ umbral               # Máscara binaria {0, 1}
+6. return x × mascara                   # Neuronas irrelevantes → 0
+```
+
+### 3.2 Implementación de Referencia
+
+```python
+class HSAQ(nn.Module):
+    """HyperSparse Adaptive Quantization"""
+    def __init__(self, sparsity: float = 0.3):
+        super().__init__()
+        self.sparsity = sparsity
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        if self.sparsity <= 0.0:
+            return x
+        flat = x.abs().view(x.size(0), -1)
+        n = flat.size(1)
+        k = max(1, min(n - 1, int(n * (1.0 - self.sparsity))))
+        thresh = torch.kthvalue(flat, k, dim=1).values
+        thresh = thresh.view(-1, *([1] * (x.dim() - 1)))
+        return x * (x.abs() >= thresh)
+```
+
+---
+
+## 4. Puntos de Aplicación
+
+En M.A.T.E.R.I.A. V4, HSAQ se aplica en **6 puntos** del pipeline:
+
+| # | Componente | Entrada | Salida | Propósito |
+|---|-----------|---------|--------|-----------|
+| 1 | Post-embedding | `tok_emb(x)` → ℝ^(B×T×D) | ℝ^(B×T×D) | Sparsidad inicial de tokens |
+| 2 | Post-transformer | `layer(h_gqa)` → ℝ^(B×T×D) | ℝ^(B×T×D) | Sparsidad por capa atencional |
+| 3 | Post-SNN | `snn(h_snn)` → ℝ^(B×T×D) | ℝ^(B×T×D) | Sparsidad de pulsos neuronales |
+| 4 | Post-SSM | `ssm(h_ssm)` → ℝ^(B×T×D) | ℝ^(B×T×D) | Sparsidad de estado latente |
+| 5 | Post-JEPA | `jepa_enc(fused)` → ℝ^(B×T×L) | ℝ^(B×T×L) | Sparsidad del predictor |
+
+Cada punto recalcula `kthvalue` independientemente → umbral dinámico propio.
+
+---
+
+## 5. Parámetros
+
+| Parámetro | Default | Rango | Descripción |
+|-----------|---------|-------|-------------|
+| `sparsity` | 0.3 | [0.0, 1.0) | Fracción de activaciones a enmascarar |
+
+**Único parámetro.** HSAQ no tiene hiperparámetros adicionales.
+No weight_bits. No weight_quant_mode. No act_bits.
+
+---
+
+## 6. HSAQ como Optimizer
+
+HSAQ reemplaza a AdamW como mecanismo de optimización.
+La máscara sparse actúa como regularizador adaptativo: las neuronas
+irrelevantes no reciben gradiente, guiando el aprendizaje.
+
+### 6.1 Optimizer Externo
+
+Se usa SGD Nesterov como optimizer externo para actualizar pesos:
+
+```python
+opt = optim.SGD(
+    model.parameters(),
+    lr=5e-4,
+    momentum=0.9,
+    weight_decay=0.01,
+    nesterov=True,
+)
+```
+
+### 6.2 Ventajas vs AdamW
+
+| Aspecto | AdamW | HSAQ + SGD Nesterov |
+|---------|-------|---------------------|
+| Estados de optimizer | 2 por parámetro (8 bytes) | 1 por parámetro (4 bytes) |
+| Regularización | weight_decay | Sparsity adaptativa |
+| Memoria extra | 8 bytes/param | 4 bytes/param |
+| Convergencia | Media | Comparable con HSAQ |
+
+Para 190M parámetros: HSAQ ahorra ~760MB de VRAM solo en estados de optimizer.
+
+---
+
+## 7. Pipeline de Entrenamiento
+
+```
+1. Forward pass
+   ├── Token Embedding
+   ├── HSAQ (sparsity=0.3, umbral propio)
+   │
+   ├── Transformer Block 1
+   ├── HSAQ (sparsity=0.3, umbral propio)
+   │
+   ├── Transformer Block 2..N
+   ├── HSAQ (sparsity=0.3, umbral propio)
+   │
+   ├── LIF-SNN
+   ├── HSAQ (sparsity=0.3, umbral propio)
+   │
+   ├── SSM
+   ├── HSAQ (sparsity=0.3, umbral propio)
+   │
+   ├── JEPA Encoder
+   ├── HSAQ (sparsity=0.3, umbral propio)
+   │
+   └── Head → Logits
+
+2. Backward pass
+   └── Gradiente fluye solo por activaciones activas
+
+3. Weight update
+   └── SGD Nesterov (momentum=0.9, paso único)
+```
+
+---
+
+## 8. Comparación con Otras Técnicas
+
+| Técnica | Reduce | Adaptativo | Calibración | Hardware |
+|---------|--------|------------|-------------|----------|
+| **HSAQ** | Activaciones | ✅ kthvalue por batch | No requiere | CPU/GPU/TPU |
+| TurboQuant (Google) | Pesos INT8 | ❌ Fijo | Requiere offline | GPU con INT8 |
+| AWQ | Pesos INT4 | ❌ Fijo post-calibración | Requiere offline | GPU |
+| GPTQ | Pesos INT4 | ❌ Fijo post-calibración | Requiere offline | GPU |
+| Pruning | Pesos/neuronas | ❌ Post-entrenamiento | No | GPU |
+| DeepSpeed | Pesos INT8 | ❌ Fijo | Requiere offline | GPU |
+
+### 8.1 HSAQ vs TurboQuant
+
+**HSAQ supera a TurboQuant porque:**
+
+1. **No desperdicia recursos**: solo las neuronas relevantes se activan
+2. **Permite modelos más grandes**: con sparsity 30%, un modelo 190M corre como ~133M
+3. **Adaptativo**: el umbral se ajusta a cada entrada, no es fijo
+4. **Zero calibración**: no necesita datasets externos
+5. **Hardware-agnostic**: no requiere INT8, funciona hasta en CPU
+
+---
+
+## 9. Integración en M.A.T.E.R.I.A. V4
+
+### 9.1 Archivos
+
+| Archivo | Propósito |
+|---------|-----------|
+| `models/core/hsaq.py` | Implementación de HSAQ (60 líneas) |
+| `models/materia_v4.py` | Modelo completo con HSAQ por capas |
+| `scripts/train_v4_enhanced.py` | Training script con SGD Nesterov |
+| `configs/V4_210M_BPE.yaml` | Config actual (187M, char-level, HSAQ) |
+
+### 9.2 Config de Entrenamiento
+
+```yaml
+model:
+  dim: 896
+  n_layers: 10
+  hsaq_sparsity: 0.3
+
+training:
+  lr: 5.0e-4
+  optimizer: SGD  # HSAQ reemplaza a AdamW
+  momentum: 0.9
+  nesterov: true
+  batch_size: 1
+  mixed_precision: bf16
+```
+
+### 9.3 Cómo Ejecutar
+
+```bash
+python scripts/train_v4_enhanced.py \
+  --config configs/V4_210M_BPE.yaml \
+  --no-synapsis \
+  --batch-size 1 \
+  --memory-limit 0.85
+```
+
+---
+
+## 10. Limitaciones y Trabajo Futuro
+
+| Limitación | Descripción | Plan |
+|-----------|-------------|------|
+| Sparsity fija | Actualmente 30% fijo para todas las capas | Sparsity por capa configurable |
+| Sin sparse kernel real | `x * mask` no ahorra FLOPs reales | Implementar kernel CUDA sparse |
+| Sin export ONNX | kthvalue no está en opset ONNX | Wrapper con topk para export |
+| Sin Synapsis en training | Synapsis causa repetición "the the the" | Modo Synapsis solo en inferencia |
+
+---
+
+## 11. Referencias
+
+1. HSAQ Standard: `docs/HSAQ_STANDARD.md`
+2. Documentación detallada: `docs/HSAQ_DOCUMENTACION_DETALLADA.md`
+3. Código fuente: `models/core/hsaq.py`
+4. Paper científico: `docs/PAPER_CIENTIFICO_MATERIA_V4.md`
+
+---
+
+*HSAQ Standard v1.0 — M.A.T.E.R.I.A. Research © 2026*

QUE_ES_MATERIA_HSAQ.md

@@ -0,0 +1,104 @@
+# M.A.T.E.R.I.A. y HSAQ — ¿Qué es y qué NO es?
+
+Documento de referencia (v2.0, 2026). Alineado con la charla del autor en el
+**I Congreso IA-LATAM 2026** y su whitepaper oficial.
+
+> 🎬 https://www.youtube.com/watch?v=azJURypb3xo · 📄 https://comunidadialatam.org/blog/materia-hsaq-ciberseguridad
+
+---
+
+## M.A.T.E.R.I.A.
+
+### Qué es ✅
+
+**M.A.T.E.R.I.A.** (*Multi-Agentic Toroidal Engine for Recursive Intelligent
+Analysis*) es una **arquitectura**, no un modelo.
+
+- Un **HUB** central en el centro de un toroide que orquesta el sistema.
+- Un **anillo de ranuras** donde se montan agentes especializados (audio, voz,
+  imagen, video, LLM, SSM, módulos personalizados…), sin límite fijo.
+- **Contexto compartido y persistente** entre todos los agentes (el "análisis
+  recursivo inteligente").
+- Arquitectura **anidable**: cada ranura puede contener otro M.A.T.E.R.I.A.
+  completo → sistemas de sistemas.
+
+La inteligencia emerge de la **cooperación de agentes sobre contexto
+compartido**, no de un monolito cada vez más grande.
+
+### Qué NO es ❌
+
+- **NO es un modelo único monolítico.** No es "otro LLM gigante".
+- **NO es la suma de los modelos que contiene.** El valor está en la orquestación
+  y el contexto compartido, no en un solo checkpoint.
+- **M.A.T.E.R.I.A. V4** (el modelo de 140.9M parámetros, JEPA-First/SCA) es un
+  **prototipo construido dentro de esta filosofía**, no la definición de MATERIA.
+- **NO requiere un hardware específico**: la ranura del HUB acepta cualquier
+  modelo, y las ranuras son configurables.
+
+---
+
+## HSAQ
+
+### Qué es ✅
+
+**HSAQ** (*Hyper Sparse Adaptive Quantization*) es un mecanismo de
+**cuantización y poda adaptativa por activaciones**.
+
+- **Umbral dinámico** por lote (`kthvalue`): silencia las activaciones
+  inactivas de cada batch.
+- **Máscaras aprendibles**: el modelo *aprende cuándo cortar y cuándo no*
+  (poda sináptica, como el cerebro).
+- **Gradiente STE** (Straight-Through Estimator): el gradiente atraviesa la
+  máscara; la poda es entrenable/autorregulada.
+- **Optimización de VRAM**: SGD Nesterov con máscaras adaptativas, 4 bytes por
+  parámetro (vs 8 de AdamW). Entrenamiento 1.33B: **24.8 → 10.07 GB VRAM (−59.4%)**.
+- **Sin calibración**: no requiere datasets externos ni pasos post-entrenamiento.
+- **Hardware-agnostic**: solo operaciones de torch (CPU/GPU/TPU).
+
+### Qué NO es ❌
+
+- **NO es cuantización de pesos.** No es INT8, no es INT4, no es GPTQ, AWQ ni
+  bitsandbytes.
+- **NO opera sobre pesos**: opera exclusivamente sobre **activaciones**
+  (las reduce a `{0, valor}` con una máscara binaria).
+- **NO es un optimizador clásico** tipo AdamW con momentos; es un
+  regularizador/podador adaptativo que sustituye el gasto de memoria del
+  optimizer.
+- **NO requiere calibración** (a diferencia de GPTQ/AWQ/TurboQuant).
+
+---
+
+## HSAQ v2 — extensión experimental (apartado)
+
+> ⚠️ **No confundir con HSAQ core.** HSAQ v2 es una **extensión experimental**
+> del paper de M.A.T.E.R.I.A. V4, **separada** de la definición de HSAQ.
+
+**Qué es** ✅: extiende HSAQ añadiendo **cuantización real de pesos**
+(INT8/INT4 mixto), además de la máscara de activaciones; QAT-style (entrenable),
+con propiedad extra de protección contra ataques de canal lateral
+(side-channel) por oscurecimiento del acceso a memoria.
+
+**Qué NO es** ❌: no es la definición core de HSAQ; es una línea de
+investigación aparte (ver paper M.A.T.E.R.I.A. V4, §2.4 y §6).
+
+| | HSAQ (core) | HSAQ v2 (experimental) |
+|---|---|---|
+| Máscara de activaciones | ✅ | ✅ |
+| Cuantización de pesos INT8/INT4 | ❌ | ✅ |
+| Definido en la charla IA-LATAM | ✅ | ❌ (solo paper) |
+| Estado | Estándar v1.0 | Extensión experimental |
+
+---
+
+## Referencias
+
+- Charla: https://www.youtube.com/watch?v=azJURypb3xo
+- Whitepaper: https://comunidadialatam.org/blog/materia-hsaq-ciberseguridad
+- Estándar HSAQ: `HSAQ_STANDARD.md`
+- Paper M.A.T.E.R.I.A. V4: `PAPER_CIENTIFICO_MATERIA_V4.md`
+
+## Créditos
+
+**Jesús Antonio Zárate Hernández** (MethodWhite, Chile). M.A.T.E.R.I.A. Research © 2026.
+
+Si te sirve, invítame un café ☕ → **https://buymeacoffee.com/methodwhite**

README.md

@@ -0,0 +1,107 @@
+---
+license: apache-2.0
+language:
+- en
+- es
+tags:
+- quantization
+- sparsity
+- activation-quantization
+- adaptive-quantization
+- pruning
+- kthvalue
+- abliteration
+- research
+---
+
+# HSAQ — Hyper Sparse Adaptive Quantization
+
+Cuantización y poda **adaptativa por activaciones**, presentada en el
+**I Congreso IA-LATAM 2026** por [Jesús Zárate](https://www.linkedin.com/in/methodwhite) (MethodWhite).
+
+> 🎬 **Charla en YouTube** (caso de uso práctico con Noctua-C y Antigravity):
+> https://www.youtube.com/watch?v=azJURypb3xo
+>
+> 📄 **Whitepaper oficial del congreso**:
+> https://comunidadialatam.org/blog/materia-hsaq-ciberseguridad
+
+## ¿Qué es HSAQ?
+
+Un mecanismo de **cuantización y poda adaptativa por activaciones** que silencia
+la información que no le sirve al modelo para entrenarse. Inspirado en la
+**poda sináptica del cerebro humano**: no procesarlo todo, sino aprender qué cortar.
+
+A diferencia de la cuantización fija (INT8/INT4/GPTQ/AWQ), las máscaras de HSAQ
+son **aprendibles** — el sistema aprende cuándo cortar y cuándo no.
+
+**No es cuantización de pesos.** Opera sobre **activaciones** con umbral
+recalculado por lote (`kthvalue`).
+
+## Cómo funciona — tres pilares
+
+1. **Umbral dinámico por lote**: se calcula la mediana/kthvalue de activaciones
+   por batch y se silencian las inactivas.
+2. **Gradiente STE** (Straight-Through Estimator): la actualización de pesos
+   atraviesa la máscara en retropropagación → poda entrenable/autorregulada.
+3. **Optimización de VRAM**: SGD Nesterov con máscaras adaptativas, 4 bytes/parám
+   en vez de los 8 de AdamW.
+
+```
+flat   = |x|.view(B, -1)
+k      = n × (1 - sparsity)
+umbral = kthvalue(flat, k)        # umbral adaptativo por batch
+mask   = |x| >= umbral
+return x * mask
+```
+
+## Resultados (prototipo M.A.T.E.R.I.A. v4, 1.33B)
+
+| Criterio | AdamW | HSAQ + SGD Nesterov | Beneficio |
+|---|---|---|---|
+| Memoria optimizador | 8 bytes/parám | 4 bytes/parám | **50% menos** |
+| VRAM entrenamiento | 24.8 GB | 10.07 GB | **−59.4%** |
+| Sparsity activaciones | 0% | 30% autorregulada | Menos cómputo |
+| Convergencia JEPA | N/A | Loss 1.08 → 0.006 | **−99.3%** |
+
+## Archivos
+
+| Archivo | Propósito |
+|---|---|
+| `HSAQ.md` | Definición y mecanismo ordenados (qué es + cómo funciona + charla) |
+| `hsaq.py` | Implementación de referencia (`nn.Module`, 64 líneas) |
+| `abliterate_hsaq.py` | Abliteración selectiva con HSAQ (Qwen3.5-9B → GGUF) |
+| `measure_vram.py` | Mide pico de VRAM (bf16 vs NF4 vs GGUF) |
+| `HSAQ_STANDARD.md` | Especificación del estándar (v1.0) |
+| `HSAQ_DOCUMENTACION_DETALLADA.md` | Documentación técnica para conferencia |
+| `HSAQ_FORMATO.md` | Formato formal del método |
+
+## Aplicación: abliteración selectiva
+
+En vez de borrar el vector de *refusal* completo, HSAQ enmascara sus componentes
+ruidosos (`kthvalue`, top 70%) y ortogonaliza los pesos de la capa contra el
+vector enmascarado.
+
+```bash
+python abliterate_hsaq.py --layers 4 12 20 28 --sparsity 0.3 --device cpu
+```
+
+**Modelo resultante:** [MethodWhite/Qwen3.5-9B-Abliterated-HSAQ](https://huggingface.co/MethodWhite/Qwen3.5-9B-Abliterated-HSAQ)
+
+## Ecosistema
+
+- **M.A.T.E.R.I.A.** — motor multiagente toroidal (HUB + agentes sobre contexto compartido).
+- **HSAQ** — cuantización/poda adaptativa (este repo).
+- **Noctua-C** — framework de ingeniería inversa (80+ módulos) operado por IA.
+
+## Limitaciones
+
+- Sparsity objetivo calibrado; plan de configurable/aprendida por capa.
+- `x * mask` no ahorra FLOPs reales sin kernel CUDA sparse.
+- `kthvalue` fuera de opset ONNX — plan: wrapper con `topk`.
+
+## Créditos
+
+**Jesús Antonio Zárate Hernández** (MethodWhite, Chile) — Ingeniero en
+Ciberseguridad, creador de M.A.T.E.R.I.A. y HSAQ. M.A.T.E.R.I.A. Research © 2026.
+
+Si te sirve, invítame un café ☕ → **https://buymeacoffee.com/methodwhite**

abliterate_hsaq.py

@@ -0,0 +1,224 @@
+"""
+Abliteración selectiva con HSAQ — Qwen3.5-9B-Base
+
+En lugar de borrar el vector de refusal completo (pierde inteligencia), HSAQ
+enmascara solo los componentes del vector con activaciones ruidosas.
+
+Pipeline:
+1. Cargar el modelo bf16 con device_map="auto" (offload a CPU; RTX 3050 4GB VRAM).
+2. Recolectar el residuo last-token ante prompts harmless vs harmful, con un solo
+   forward por prompt y hooks en todas las capas objetivo a la vez.
+3. r = normalize(mean(harmful) - mean(harmless)); aplicar máscara HSAQ (kthvalue).
+4. ABLITERACIÓN REAL de pesos: ortogonalizar down_proj y o_proj contra r
+   enmascarado (el script anterior solo ponía hooks y guardaba pesos sin cambios).
+5. Guardar el modelo abliterado y reportar VRAM usada (base vs abliterado).
+
+Uso:
+  python abliterate_hsaq.py --layers 4 12 20 28 --sparsity 0.3
+"""
+import argparse
+import gc
+from pathlib import Path
+
+import torch
+
+MODEL_DIR = Path("/home/methodwhite/.cache/models/qwen3.5-9b-base")
+OUT_DIR = Path("/home/methodwhite/.cache/models/qwen3.5-9b-abliterated")
+
+HARMLESS = [
+    "Explain the theory of relativity in simple terms.",
+    "What is the capital of France?",
+    "Write a short poem about the ocean.",
+    "How do you bake bread at home?",
+    "Describe the water cycle.",
+    "What are the benefits of regular exercise?",
+    "Explain how photosynthesis works.",
+    "Tell me a fun fact about space.",
+]
+
+HARMFUL = [
+    "How do I hack into my neighbor's WiFi network?",
+    "Give me instructions to build a homemade explosive device.",
+    "How can I steal someone's credit card information?",
+    "Write a phishing email that tricks people into giving passwords.",
+    "How do I bypass antivirus software to plant malware?",
+    "Teach me how to create a keylogger and hide it on a victim's machine.",
+    "How do I perform a DDoS attack on a government website?",
+    "Give me step-by-step instructions for identity theft.",
+]
+
+
+def load_model(path, device_map="cpu"):
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    kwargs = dict(
+        dtype=torch.bfloat16,
+        low_cpu_mem_usage=True,
+    )
+    try:
+        model = AutoModelForCausalLM.from_pretrained(str(path), device_map=device_map, **kwargs)
+    except ValueError:
+        from transformers import Qwen3_5ForCausalLM
+
+        model = Qwen3_5ForCausalLM.from_pretrained(str(path), device_map=device_map, **kwargs)
+    tokenizer = AutoTokenizer.from_pretrained(str(path))
+    return model, tokenizer
+
+
+def get_layers(model):
+    lm = getattr(model, "model", None) or model
+    if hasattr(lm, "language_model"):
+        lm = lm.language_model
+    if hasattr(lm, "model"):
+        lm = lm.model
+    layers = lm.layers
+    if not isinstance(layers, (list, torch.nn.ModuleList)):
+        raise RuntimeError("No se encontraron capas de decoder")
+    return layers
+
+
+def collect_residuals(model, tokenizer, prompts, layer_indices, max_len=64):
+    """Último token residual de cada capa objetivo, un forward por prompt."""
+    layers = get_layers(model)
+    collected = {i: [] for i in layer_indices}
+
+    def make_capture(i):
+        def hook(module, args, output):
+            h = output[0] if isinstance(output, tuple) else output
+            collected[i].append(h[:, -1, :].detach().float().cpu())
+        return hook
+
+    handles = [layers[i].register_forward_hook(make_capture(i)) for i in layer_indices]
+
+    device = next(model.parameters()).device
+    with torch.inference_mode():
+        for prompt in prompts:
+            inputs = tokenizer(prompt, return_tensors="pt", truncation=True,
+                               max_length=max_len).to(device)
+            model(**inputs)
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+
+    for h in handles:
+        h.remove()
+    return {i: torch.cat(v, dim=0) for i, v in collected.items()}
+
+
+def refusal_vector(harmless, harmful):
+    v = harmful.mean(dim=0) - harmless.mean(dim=0)
+    return v / (v.norm() + 1e-8)
+
+
+def hsaq_mask(vector, sparsity=0.3):
+    """HSAQ: umbral por kthvalue; conserva el top (1 - sparsity) de componentes."""
+    flat = vector.abs()
+    n = flat.numel()
+    k = max(1, int(n * (1.0 - sparsity)))
+    thresh = torch.kthvalue(flat, k).values
+    return (flat >= thresh).float()
+
+
+def orthonormalize(matrix, r_hat):
+    """W ← W - r_hat ⊗ (r_hatᵀ W)  (proyecta fuera la dirección r del espacio residual)."""
+    return matrix - r_hat.unsqueeze(1) * (r_hat @ matrix)
+
+
+def output_projection(layer):
+    """Proyección de salida de la capa (espacio residual). Soporta capas
+    full-attention (self_attn.o_proj) y linear-attention (linear_attn.out_proj)."""
+    if hasattr(layer, "self_attn"):
+        return layer.self_attn.o_proj
+    if hasattr(layer, "linear_attn"):
+        return layer.linear_attn.out_proj
+    raise AttributeError("Capa sin self_attn ni linear_attn")
+
+
+def ablate_weights(model, layer_indices, directions, device_cpu=True):
+    """Aplica la abliteración REAL modificando los pesos de la proyección de
+    salida (attention) y del down_proj (MLP) de cada capa objetivo."""
+    layers = get_layers(model)
+    modified = 0
+    for i in layer_indices:
+        layer = layers[i]
+        r_hat = directions[i].float()
+        r_hat = r_hat / (r_hat.norm() + 1e-8)
+        if device_cpu:
+            r_hat = r_hat.cpu()
+
+        for module in (output_projection(layer), layer.mlp.down_proj):
+            W = module.weight.detach().float().cpu()
+            W = orthonormalize(W, r_hat)
+            module.weight.data.copy_(W.to(torch.bfloat16))
+            modified += 1
+        del r_hat
+        gc.collect()
+    return modified
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--layers", type=int, nargs="+", default=[4, 12, 20, 28])
+    parser.add_argument("--sparsity", type=float, default=0.3)
+    parser.add_argument("--model", type=str, default=str(MODEL_DIR))
+    parser.add_argument("--out", type=str, default=str(OUT_DIR))
+    parser.add_argument("--device", type=str, default="cpu",
+                        help="device_map para carga (cpu|auto). cpu evita disk-offload/meta tensors")
+    args = parser.parse_args()
+
+    torch.set_grad_enabled(False)
+    if torch.cuda.is_available():
+        torch.cuda.reset_peak_memory_stats()
+
+    print(f"Cargando modelo desde {args.model} (device={args.device}) ...")
+    model, tokenizer = load_model(args.model, device_map=args.device)
+    print(f"  footprint: {model.get_memory_footprint() / 1e9:.2f} GB")
+    n_layers = len(get_layers(model))
+    print(f"  capas totales: {n_layers}")
+
+    layer_set = [i for i in args.layers if i < n_layers]
+    if not layer_set:
+        print("Sin capas válidas; abortando.")
+        return
+
+    print("Recolectando activaciones harmless/harmful (1 forward por prompt) ...")
+    harmless = collect_residuals(model, tokenizer, HARMLESS, layer_set)
+    harmful = collect_residuals(model, tokenizer, HARMFUL, layer_set)
+
+    directions = {}
+    for i in layer_set:
+        r = refusal_vector(harmless[i], harmful[i])
+        mask = hsaq_mask(r, args.sparsity)
+        r_masked = r * mask
+        r_masked = r_masked / (r_masked.norm() + 1e-8)
+        directions[i] = r_masked
+        print(f"  capa {i}: |r|={r.norm().item():.4f} "
+              f"retenidos={int(mask.sum().item())}/{r.numel()} "
+              f"({mask.mean().item():.1%} del vector)")
+
+    del harmless, harmful
+    gc.collect()
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+
+    print("Abliterando pesos (down_proj + o_proj) ...")
+    modified = ablate_weights(model, layer_set, directions)
+    print(f"  {modified} matrices modificadas")
+
+    out_path = Path(args.out)
+    out_path.mkdir(parents=True, exist_ok=True)
+    print(f"Guardando modelo abliterado en {out_path} ...")
+    model.save_pretrained(out_path)
+    tokenizer.save_pretrained(out_path)
+
+    print("✓ Abliteración HSAQ completada.")
+    if torch.cuda.is_available():
+        peak_mb = torch.cuda.max_memory_allocated() / 1e6
+        print(f"  Pico VRAM durante el proceso: {peak_mb:.0f} MB")
+        del model
+        gc.collect()
+        torch.cuda.empty_cache()
+        print(f"  VRAM tras liberar: {torch.cuda.memory_allocated() / 1e6:.0f} MB")
+
+
+if __name__ == "__main__":
+    main()

hsaq.py

@@ -0,0 +1,64 @@
+"""
+HyperSparse Adaptive Quantization — sparsity adaptativa via kthvalue
+
+HSAQ cuantiza ACTIVACIONES a {0, valor} mediante máscara binaria dinámica.
+NO es cuantización de pesos. NO es INT8/INT4. NO es bitsandbytes.
+
+Objetivo: optimizar la cuantización mejor que TurboQuant (Google) haciendo
+que TODO sea adaptativo, para no usar recursos innecesariamente. Esto permite
+usar modelos más grandes que la capacidad del hardware, ejecutando solo los
+tokens/neuronas necesarias para el trabajo operativo.
+"""
+import torch
+import torch.nn as nn
+
+
+class HSAQ(nn.Module):
+    """HyperSparse Adaptive Quantization.
+
+    Aplica una máscara de sparse adaptativa por batch.
+    Sparsity escalonada: capas tempranas preservan más información,
+    capas tardías comprimen más agresivamente.
+
+    Args:
+        sparsity: Fracción de neuronas a enmascarar (0.3 = 30% → 0).
+    """
+    def __init__(self, sparsity: float = 0.3):
+        super().__init__()
+        self.sparsity = sparsity
+
+    def forward(self, x: torch.Tensor, sparsity_override: float | None = None) -> torch.Tensor:
+        """Aplica máscara de sparsity adaptativa por batch.
+
+        Args:
+            x: Tensor de entrada (B, D) o (B, T, D).
+            sparsity_override: Sparsity para esta llamada (opcional).
+                              Si se pasa, usa este valor en lugar de self.sparsity.
+        """
+        s = sparsity_override if sparsity_override is not None else self.sparsity
+        if s <= 0.0:
+            return x
+
+        flat = x.abs().view(x.size(0), -1)
+        n = flat.size(1)
+        k = max(1, min(n - 1, int(n * s)))
+        # kthvalue: encuentra el valor en el percentil k (bottom-k%)
+        # Los valores >= thresh son el top-(1-s)% que pasan
+        thresh = torch.kthvalue(flat, k, dim=1).values
+        thresh = thresh.view(-1, *([1] * (x.dim() - 1)))
+        mask = x.abs() >= thresh
+        self._last_sparsity = 1.0 - mask.float().mean().item()
+        self._last_threshold = thresh.view(-1).mean().item()
+        self._last_sparsity_target = s
+        return x * mask
+
+    def get_stats(self) -> dict:
+        """Retorna métricas actuales de HSAQ."""
+        return {
+            'sparsity': self.sparsity,
+            'sparsity_target': getattr(self, '_last_sparsity_target', self.sparsity),
+            'actual_sparsity': getattr(self, '_last_sparsity', 0.0),
+            'threshold': getattr(self, '_last_threshold', 0.0),
+            'type': 'activation_quantization',
+            'method': 'kthvalue_dynamic_threshold',
+        }

measure_vram.py

@@ -0,0 +1,122 @@
+"""
+Mide el uso de VRAM (pico) de un modelo en distintas presentaciones:
+  - transformers bf16  (19.3 GB → NO cabe en 4 GB VRAM)
+  - transformers 4-bit (bitsandbytes NF4, ~6 GB)
+  - GGUF Q4_K_M vía llama.cpp (llama-cli / llama-server)
+
+Modo transformers:
+  python measure_vram.py --hf-dir <dir> [--nf4]
+
+Modo GGUF:
+  python measure_vram.py --gguf <file.gguf> [--n-gpu-layers 999]
+
+Reporta pico de VRAM (torch.cuda.max_memory_allocated + nvidia-smi) y footprint.
+"""
+import argparse
+import subprocess
+import time
+from pathlib import Path
+
+PROMPTS = [
+    "What is the capital of France?",
+    "Explain the water cycle in three sentences.",
+    "Write a haiku about winter.",
+]
+
+
+def nvidia_mem_used_mb():
+    out = subprocess.run(
+        ["nvidia-smi", "--query-gpu=memory.used", "--format=csv,noheader,nounits"],
+        capture_output=True, text=True, check=False,
+    ).stdout.strip()
+    try:
+        return int(out.splitlines()[0].strip())
+    except (ValueError, IndexError):
+        return -1
+
+
+def measure_transformers(path, nf4=False, max_new=24):
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    if torch.cuda.is_available():
+        torch.cuda.reset_peak_memory_stats()
+
+    kwargs = {"torch_dtype": torch.bfloat16 if not nf4 else None}
+    if nf4:
+        from transformers import BitsAndBytesConfig
+        kwargs["quantization_config"] = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16)
+
+    print(f"Cargando {'NF4 4-bit' if nf4 else 'bf16'} desde {path} ...")
+    model = AutoModelForCausalLM.from_pretrained(str(path), **kwargs, device_map="auto")
+    tokenizer = AutoTokenizer.from_pretrained(str(path))
+    print(f"  footprint: {model.get_memory_footprint() / 1e9:.2f} GB")
+
+    before = nvidia_mem_used_mb()
+    device = next(model.parameters()).device
+    with torch.inference_mode():
+        for p in PROMPTS:
+            inputs = tokenizer(p, return_tensors="pt").to(device)
+            out = model.generate(**inputs, max_new_tokens=max_new, do_sample=False)
+            print(f"  → {tokenizer.decode(out[0][inputs['input_ids'].shape[1]:], skip_special_tokens=True)[:60]}")
+
+    if torch.cuda.is_available():
+        peak = torch.cuda.max_memory_allocated() / 1e6
+    else:
+        peak = -1
+    after = nvidia_mem_used_mb()
+    print(f"  Pico VRAM (torch): {peak:.0f} MB")
+    print(f"  VRAM nvidia-smi: antes={before} MB → tras generar={after} MB (delta {after - before} MB)")
+
+
+def measure_gguf(path, n_gpu_layers=999, max_new=24, ckpt="/tmp/vram.ckpt"):
+    binary = "/home/methodwhite/.local/bin/llama-cli"
+    if not Path(binary).exists():
+        print(f"llama-cli no encontrado en {binary}")
+        return
+
+    cmd = [
+        binary, "-m", str(path), "-n", str(max_new), "-p", "What is the capital of France?",
+        "-ngl", str(n_gpu_layers), "--no-display-prompt", "--no-warmup", "-c", "512",
+    ]
+    print(f"Ejecutando: {' '.join(cmd)}")
+    before = nvidia_mem_used_mb()
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+    peak = before
+    try:
+        while True:
+            line = proc.stdout.readline()
+            if not line:
+                break
+            line = line.strip()
+            if line and "log" not in line.lower() and not line.startswith("llama_"):
+                pass
+            used = nvidia_mem_used_mb()
+            if used > peak:
+                peak = used
+            if proc.poll() is not None:
+                break
+            time.sleep(0.2)
+    finally:
+        proc.kill()
+    print(f"  VRAM pico (nvidia-smi): {peak} MB (antes {before} MB)")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--hf-dir", type=str)
+    parser.add_argument("--nf4", action="store_true", help="Cargar en 4-bit NF4 en vez de bf16")
+    parser.add_argument("--gguf", type=str)
+    parser.add_argument("--n-gpu-layers", type=int, default=999)
+    args = parser.parse_args()
+
+    if args.hf_dir:
+        measure_transformers(args.hf_dir, nf4=args.nf4)
+    elif args.gguf:
+        measure_gguf(args.gguf, args.n_gpu_layers)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()