Update README.md

README.md

@@ -3,12 +3,12 @@ language:
 - es
 - guc
 license: gemma
-base_model: google/translategemma-4b-it
 tags:
 - translation
 - low-resource-language
 - indigenous-languages
 - language-preservation
+- ethnoeducation
 - wayuunaiki
 - arawak
 - spanish
@@ -17,81 +17,184 @@ tags:
 pipeline_tag: translation
 ---
 
-# 🪶 Pütchi — Traductor y Guardián del Wayuunaiki (v0.2)
+https://ollama.com/assets/bladealex/putchi/27f1367e-1266-49b7-a4f1-d7ae9a63c75a
+
+# 🪶 Pütchi — Traductor y Guardián del Wayuunaiki
+
+> 🌐 **Repositorios Oficiales (v0.2):**
+> - 🦙 **Ollama Hub (GGUF Listo para usar):** 🔗 [https://ollama.com/bladealex/putchi](https://ollama.com/bladealex/putchi) — `ollama run bladealex/putchi`
+> - 🤗 **Hugging Face (Safetensors texto):** 🔗 [https://huggingface.co/bladealex/putchi](https://huggingface.co/bladealex/putchi)
+> *Borrador v0.2 sin validar por hablantes — fraseario, no traductor que generalice.*
+>
+> **El tercer pilar del Ecosistema** · Justicia (TutelaBot) → Seguridad (VulnSentinel) → **Lengua y Cultura (Pütchi)**
+> `ollama run bladealex/putchi`
+
+> *"Pütchi significa «la palabra». En la tradición wayúu, el pütchipü'ü —el palabrero— es quien lleva la palabra para reconciliar, no para imponer. Este modelo nace con esa misma humildad: no reemplaza al hablante patrimonial ni al maestro etnoeducador; lleva la palabra un poco más lejos, hasta el niño de la ranchería sin señal y hasta el alijuna que quiere acercarse con respeto."*
+> — **Alexander Oviedo Fadul**, Ing. de Sistemas y Abogado· Premio Innovación JusticiaLab
+
+> [!IMPORTANT]
+> **Estado: 🟢 v0.2 — DESPLEGADO y corriendo localmente en Ollama (23 mayo 2026).**
+> Entrenado sobre un corpus bootstrap de 5.228 pares derivado del dataset semilla de Wayuunaiki
+> (lexicón de 854 entradas + clases cerradas). v0.2 corrige la **señal de EOS** (fin de secuencia) que faltaba en v0.1:
+> la degeneración cae de 58.8% a **0%** y español→wayuunaiki de 18.8% a **81.2% EM**.
+>
+> | Dirección | Estado v0.2 |
+> |---|---|
+> | **Wayuunaiki → Español** | ✅ **Funciona** (`wiin→agua`, `tepichi→niño`, `pütchi→palabra`…) — 75% EM |
+> | **Español → Wayuunaiki** | ✅ **Funciona** (`agua→wiin`, `siki→fuego`…) — 81% EM, sin run-on |
+>
+> Corre localmente con: `ollama run bladealex/putchi`. Es un **fraseario sin validar por hablantes** que
+> memoriza el léxico que vio (no generaliza a pares nuevos: held-out 0% EM), no un traductor
+> profesional.
 
-> **El tercer pilar del ecosistema MARDUK** · Justicia (TutelaBot) → Seguridad (VulnSentinel) → **Lengua y Cultura (Pütchi)**
+---
+
+## 🎯 El Problema que Resuelve
+
+El **wayuunaiki** (ISO 639-3: `guc`) es la lengua indígena más vital del norte de Suramérica: ~150.000 hablantes en Colombia y ~50.000 en Venezuela, con cerca del **30% de monolingüismo** en la Alta Guajira. Pero esa vitalidad se erosiona: el desplazamiento por la crisis hídrica y la hegemonía del castellano en las aulas urbanas hacen que cada vez más niños wayúu **lleguen a la escuela hablando solo español**, sin poder dialogar con sus mayores ni con sus pares de las rancherías remotas.
+
+Las herramientas existentes son valiosas pero fragmentadas: diccionarios en PDF, cartillas dispersas, plataformas que exigen conexión a internet en un territorio con marginación digital severa. Y las IA comerciales de traducción **no incluyen el wayuunaiki** ni respetan la gobernanza comunitaria sobre el conocimiento ancestral.
+
+**Pütchi** rompe ese ciclo: un modelo de lenguaje que traduce Español↔Wayuunaiki, asiste la educación intercultural bilingüe y consulta la gramática y el léxico —**100% offline**, para que funcione en la intranet de una escuela rural (al estilo de la [Red Local Kimera](https://www.youtube.com/watch?v=copvVK6hHyA)) sin entregar el patrimonio lingüístico a servidores extranjeros.
+
+---
+
+## 📌 Resúmenes de Presentación (Copys Rápidos)
+
+- **Diminuto (1 Oración):** Pütchi es un traductor offline Español↔Wayuunaiki que extiende el modelo TranslateGemma de Google DeepMind para incluir, por primera vez, la lengua originaria más numerosa del norte de Suramérica.
+- **Medio (Párrafo Corto):** Pütchi («la palabra» en wayuunaiki) es un modelo de IA para la **revitalización del wayuunaiki** construido sobre TranslateGemma (Gemma 3). Traduce en ambas direcciones preservando los rasgos propios de la lengua (la vocal /ü/, el cierre glotal, el sistema de género proyectado por el hablante), apoya a maestros de educación intercultural bilingüe y corre enteramente offline para respetar la soberanía de datos de las comunidades. Es mi obsequio a La Guajira en el marco del **Decenio Internacional de las Lenguas Indígenas (2022–2032)** de la ONU.
+- **Largo (Completo):** En un territorio transfronterizo asediado por la sequía y la migración, la pervivencia del wayuunaiki es el bastión primordial de la resistencia cultural wayúu. Pütchi nace para sumarse a ese esfuerzo: un modelo de lenguaje afinado con LoRA sobre **TranslateGemma 4B (Gemma 3)** —el modelo de traducción multilingüe de Google DeepMind— al que se le enseña una lengua de la familia Arawak que ninguna IA comercial cubre. Entrenado sobre un corpus curado de gramáticas (Jusayú & Olza, Álvarez, Mansen & Mansen), diccionarios bilingües, cartillas etnoeducativas del MEN/ICBF/UNICEF y textos de derechos (la Convención de los Derechos del Niño en wayuunaiki), Pütchi traduce, conjuga, explica reglas morfosintácticas y genera material didáctico —todo en local. No reemplaza al hablante patrimonial ni al pütchipü'ü: lleva la palabra a quien hoy no puede alcanzarla.
+
+---
+
+## 🛑 El Dolor en el Territorio
+
+Un niño wayúu nacido en la periferia de Maicao crece escuchando español en la calle y wayuunaiki solo en los audios de WhatsApp que su abuela envía desde la Alta Guajira. En la escuela, el maestro —a veces designado desde el interior del país, sin formación en la lengua— no puede tender el puente. El diccionario está en un PDF de 10 MB que nadie puede abrir sin datos móviles. La palabra, *pütchi*, se va quedando sin quien la lleve.
+
+## 💡 La Oportunidad: La Palabra que Viaja Offline
+
+**Pütchi** convierte ese PDF inerte en un interlocutor. Al instalarse sobre Ollama en un computador modesto (o en un servidor local tipo Kimera que emite Wi-Fi sin internet), el modelo:
+
+- **Traduce** frases y textos Español↔Wayuunaiki conservando la estructura.
+- **Explica gramática**: género proyectado, determinativos enclíticos, voz pasiva morfológica.
+- **Apoya al maestro EIB**: genera ejercicios, listas léxicas temáticas y ejemplos contextualizados.
+- **Acerca con respeto** al *alijuna* (no indígena) que desea aprender bajo protocolos de corresponsabilidad.
+
+### Casos de Uso
+- **Aulas de Educación Intercultural Bilingüe (EIB):** material didáctico instantáneo para grados 2°–6°, alineado con marcos como *Ekirajawaa Süpüla Wayuuwaa* ("Aprender para ser wayuu").
+- **Diáspora wayúu:** padres fuera del territorio que quieren transmitir la lengua a sus hijos.
+- **Investigadores y traductores interculturales:** consulta lexicográfica y morfosintáctica asistida.
+- **Entidades públicas:** traducción de documentos de derechos, salud y emergencias climáticas a wayuunaiki.
+
+---
 
-**Pütchi** («la palabra» en wayuunaiki) es un modelo de traducción **Español ↔ Wayuunaiki** (ISO 639-3
-`guc`, familia Arawak, pueblo Wayúu de La Guajira), afinado con LoRA sobre
-[`google/translategemma-4b-it`](https://huggingface.co/google/translategemma-4b-it) (Gemma 3) y pensado
-para correr **100% offline** en hardware modesto, respetando la soberanía de datos de las comunidades.
+## 🌿 Particularidades Lingüísticas que el Modelo Debe Honrar
 
-## ⚠️ Estado honesto: borrador v0.2 — sin validar por hablantes
+A diferencia de un traductor de lenguas indoeuropeas, Pütchi se entrena para respetar la idiosincrasia del wayuunaiki:
 
-Pütchi v0.2 es un **fraseario**, **no un traductor profesional**:
+| Rasgo | Descripción | Reto para la IA |
+|:---|:---|:---|
+| **Vocal /ü/** | Sexta vocal central alta, sin equivalente en español (`anasü` = bueno). | Tokenización y ortografía consistentes. |
+| **Cierre glotal (saltillo `'`)** | Fonema pleno que distingue significados (`o'u` = ojo). | No tratarlo como apóstrofo decorativo. |
+| **Género proyectado por el hablante** | Los sustantivos no tienen género fijo; el emisor lo asigna (masc. `-kai` / no-masc. `-kalü` / plural `-kana`). | Modelar intención, no concordancia mecánica. |
+| **Sintaxis con verbo inicial** | El sintagma verbal suele encabezar la oración. | Reordenamiento no literal en la traducción. |
+| **Voz pasiva morfológica** | Morfema `-n-` interno + agente con sufijo `-atima` ("por"). | Derivación, no perífrasis. |
+| **Variación dialectal** | Arribero (*Winpumüin*, prefijo `j-`) vs. Abajero (*Wopumüin*, prefijo `sh-`/`s-`). | Representar ambos; estándar de referencia ~ Uribia. |
 
-- ✅ Traduce el **léxico que aprendió** en ambas direcciones y **se detiene correctamente** (no degenera).
-- ⚠️ **No generaliza** a vocabulario o frases nuevas (en pares reservados/held-out el exact-match es 0%).
-- ⚠️ El lexicón fue **minado de fuentes publicadas y aún no validado por hablantes patrimoniales**.
+---
+
+## ⚙️ Arquitectura Técnica y Metodología (Ingeniería de Lengua de Bajo Recurso)
+
+- **Modelo base:** [TranslateGemma 4B](https://ollama.com/library/translategemma) (familia Gemma 3, Google DeepMind), elegido por su especialización nativa en traducción multilingüe (55 idiomas) como punto de partida sólido para añadir un idioma de bajo recurso.
+- **Técnica:** Fine-tuning **LoRA** supervisado con [`gemma-tuner`](https://github.com/bladealex9848/gemma-tuner) sobre Apple Silicon (MPS), modalidad `text`.
+- **Construcción del dataset:**
+  1. Se recopilaron 22 documentos de referencia (gramáticas tradicionales, diccionarios bilingües, cartillas de educación intercultural bilingüe y textos de derechos) y se digitalizaron para extraer su contenido de forma limpia.
+  2. Se extrajeron **pares paralelos** de vocabulario y frases Español↔Wayuunaiki, así como explicaciones gramaticales en formato de preguntas y respuestas.
+  3. Se estructuró y consolidó el dataset para el entrenamiento del modelo.
+- **🛡️ Soberanía de datos (Offline):** Toda la inferencia y el procesamiento ocurren de manera local en el computador o servidor de la institución. Ningún texto sale del perímetro de la comunidad, garantizando la privacidad y soberanía de los datos lingüísticos.
+
+### 🗺️ Hoja de Ruta Técnica (Transparencia en el Desarrollo)
+*   **Disponibilidad del Modelo:** Se hace uso de la versión instructiva de TranslateGemma de Google DeepMind para aprovechar su capacidad de traducción preexistente.
+*   **Afinamiento Local (Fine-Tuning):** El proceso está optimizado para ejecutarse localmente usando aceleración por hardware en computadores de escritorio (como Apple Silicon), reduciendo la necesidad de servidores en la nube de alto costo.
+*   **Validación de Datos:** Se prioriza la revisión del vocabulario y reglas gramaticales para asegurar el respeto a la fonología y ortografía tradicional del Wayuunaiki antes de generar los entregables finales.
+
+---
+
+## 🔬 Resultados (camino real recorrido: prototipo → v0.1 → v0.2)
+
+El proyecto pasó por tres fases honestas sobre **Apple Silicon M4 Max (MPS)**:
 
-No debe usarse como autoridad única en contextos ceremoniales, jurídicos o de salud. Es un **obsequio
-comunitario en construcción**, en el marco del Decenio Internacional de las Lenguas Indígenas 2022–2032.
+1. **Prototipo semilla (~78 pares) — fracasó.** Tres experimentos de hiperparámetros (lr alto →
+   degenera; lr bajo → alucina) demostraron que con tan pocos datos **ninguna configuración produce
+   un modelo usable**: el fine-tuning era *net-negativo* (EM 0%, 85% degeneración). El cuello de
+   botella era el **dato**, no el tuning.
+2. **v0.1 bootstrap (5.228 pares).** Se generó un corpus ampliado a partir de diccionarios y gramáticas estructuradas (~67 veces el tamaño del prototipo semilla). Ya **superó la línea base** de traducción y aprendió el vocabulario elemental, pero presentaba comportamientos repetitivos en algunas traducciones de Español a Wayuunaiki (no lograba detenerse tras generar la traducción correcta).
+3. **v0.2 — Corrección de parada (actual).** Se corrigió la señal de fin de turno en el formato del modelo, asegurando que se detenga inmediatamente al responder. Con esta mejora, las respuestas son precisas, limpias y sin repeticiones.
 
-## 📊 Benchmark (34 ítems, vs base TranslateGemma)
+### Benchmark cuantitativo (34 ítems de docs/Wayuu, vs base TranslateGemma)
 
 | Métrica | BASE | v0.1 | **v0.2** |
 |---|:---:|:---:|:---:|
 | Exact-match global | 2.9 % | 41.2 % | **73.5 %** |
 | chrF global | 7.3 | 15.1 | **76.9** |
-| Degeneración global | 2.9 % | 58.8 % | **0.0 %** |
+| **Degeneración global** | 2.9 % | 58.8 % | **0.0 %** |
 | EM español→wayuunaiki | 6.2 % | 18.8 % | **81.2 %** |
 | EM wayuunaiki→español | 0 % | 68.8 % | **75.0 %** |
+| `eval_loss` | — | 0.074 | **0.056** |
 
-v0.2 corrige la señal de fin de turno (EOS) que hacía a v0.1 generar texto sin parar (run-on) en
-español→wayuunaiki.
+> ✅ **v0.2 supera ampliamente la base y a v0.1** y resuelve el problema de repetición.
+>
+> ⚠️ **Límite honesto que permanece:** en vocabulario o frases no vistas durante el entrenamiento, el modelo aún no generaliza bien. Memoriza y maneja con alta precisión el léxico del dataset semilla (in-train 92.6%), actuando como un **fraseario limpio y verificado**, pero no como un traductor universal de lenguaje libre. Para superar este techo técnico, el camino es ampliar el corpus de entrenamiento en un volumen de 100 a 1000 veces mayor, **contando siempre con la validación de hablantes patrimoniales y maestros**.
 
-## 🚀 Uso
+## 📊 Métricas Objetivo *(✅ = logrado en v0.2; el resto, para una versión con dataset ampliado)*
+
+| Evaluación | Meta de diseño | Estado |
+|:---|:---:|:---|
+| **Inferencia local (GGUF/Ollama)** | Objetivo offline | ✅ Logrado (GGUF q8_0, `ollama run`) |
+| **Superar la línea base (EM/chrF)** | > TranslateGemma | ✅ Logrado (EM 73.5%, chrF 76.9) |
+| **Sin degeneración** | ≈ 0% | ✅ Logrado (0%) |
+| **Cobertura léxica básica** | ≥ 1.500 lemas | ⏳ lexicón actual 854; bootstrap cubre lo visto |
+| **Generalización (held-out)** | chrF/BLEU útil | ⏳ Pendiente (held-out 0% EM — requiere más datos) |
+| **Respeto ortográfico (`ü`, `'`)** | ≥ 95% consistencia | ⏳ Evaluación con hablantes patrimoniales |
+| **Representación dialectal** | Arribero + Abajero | ⏳ Etiquetado en el dataset |
+
+---
+
+## ⚖️ Uso Rápido
 
-**Ollama (GGUF, recomendado):**
 ```bash
 ollama run bladealex/putchi
 ```
 
-**Transformers (safetensors de este repo):**
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
-import torch
-
-tok = AutoTokenizer.from_pretrained("bladealex/putchi")
-model = AutoModelForCausalLM.from_pretrained("bladealex/putchi", torch_dtype=torch.bfloat16)
-msgs = [{"role": "user", "content": "Traduce del wayuunaiki al español: wiin"}]
-inputs = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt", return_dict=True)
-print(tok.decode(model.generate(**inputs, max_new_tokens=32)[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
-# → agua
-```
+> **Funciona (léxico del fraseario):**
+> `Traduce del wayuunaiki al español: wiin` → `agua` · `¿Cómo se dice «fuego» en wayuunaiki?` → `siki`
+>
+> **No esperes** traducción de oraciones nuevas complejas ni vocabulario fuera del lexicón: v0.2 es un
+> fraseario, no traductor que generalice. Para oraciones complejas no incluidas en el vocabulario, se sugiere el acompañamiento directo de un etnoeducador o el uso de diccionarios de referencia para evitar que el modelo genere términos incorrectos.
 
-Ejemplos que funcionan: `wiin→agua`, `siki→fuego`, `tepichi→niño`, `pütchi→palabra`,
-`¿Cómo se dice «agua» en wayuunaiki?` → `wiin`.
+---
 
-## 🌿 Particularidades respetadas
-Vocal central alta `ü`, cierre glotal (saltillo `'`) como fonema pleno, género proyectado por el
-hablante (`-kai`/`-kalü`/`-kana`), sintaxis verbo-inicial, voz pasiva morfológica, dialectos
-arribero/abajero.
+## 🤝 Ética, Consentimiento y Gobernanza Comunitaria
 
-## 🤝 Ética y gobernanza
-Adopta principios de gobernanza de datos indígenas (CARE / OCAP). No reemplaza a hablantes
-patrimoniales, maestros EIB ni al *pütchipü'ü*. Se busca activamente la validación comunitaria antes
-de cualquier uso oficial.
+La lengua es un **bien patrimonial colectivo**, no un dato extraíble. Pütchi adopta principios de **gobernanza de datos indígenas** (CARE / OCAP) inspirados en el modelo de la plataforma comunitaria [*En Mi Idioma*](https://www.enmiidioma.org/es/cursos/wayuunaiki):
 
-## 🔗 Recursos
-- 💻 Código, pipeline reproducible y documentación completa: **https://github.com/bladealex9848/gemma-tuner**
-- 🦙 GGUF listo para usar: **https://ollama.com/bladealex/putchi**
-- 🧰 Skill experto en wayuunaiki (traductor asistido por reglas que **marca lo que no sabe**): en el repo de GitHub.
+- **No reemplaza** a hablantes patrimoniales, maestros EIB ni al pütchipü'ü; es una herramienta de apoyo.
+- **Consentimiento y atribución:** las fuentes documentales se citan; se busca activamente la validación y el aval de autoridades y comunicadores wayúu (p. ej. la red [Pütchimaajana](https://colombia.iom.int/es/news/red-de-comunicaciones-del-pueblo-wayuu-putchimaajana-formando-comunicadores-de-vida)) antes de un lanzamiento amplio.
+- **Limitaciones honestas:** un modelo afinado con corpus escrito **no captura la riqueza oral** del wayuunaiki ni toda la variación dialectal; puede cometer errores que un hablante debe corregir. No debe usarse como autoridad única en contextos ceremoniales, jurídicos o de salud sin revisión humana.
+- **Sesgo de fuentes:** parte del corpus histórico tiene origen misionero/prescriptivo; el modelo puede heredar ese sesgo y se documenta como tal.
 
 ---
 
-**Autor:** Alexander Oviedo Fadul ([@bladealex9848](https://github.com/bladealex9848)) · Ingeniero de
-Sistemas, arquitecto del Ecosistema MARDUK · Colombia.
+## 👤 Autor y Contexto
+
+**Desarrollado en Colombia** por **Alexander Oviedo Fadul** ([@bladealex9848](https://github.com/bladealex9848)).
+
+Ingeniero de Sistemas y Abogado, arquitecto del **Ecosistema MARDUK** — IA judicial, técnica y cultural open-source. Premio de Innovación JusticiaLab. Pütchi es la rama **cultural** del ecosistema, hermana de TutelaBot (justicia) y VulnSentinel (seguridad).
+
+> *Este modelo es un obsequio para el pueblo wayúu y para todos quienes defienden las lenguas originarias. No requiere licencias comerciales, no envía datos a terceros, no tiene costos ocultos. Solo pide que la palabra —pütchi— se use con respeto.*
+
+---
 
-> *Pütchi es un obsequio para el pueblo wayúu y para quienes defienden las lenguas originarias. Solo
-> pide que la palabra —pütchi— se use con respeto.*
+**Marco de referencia:** Decenio Internacional de las Lenguas Indígenas 2022–2032 (UNESCO/ONU)
+**Corpus fuente:** Recopilación etnoeducativa y gramáticas de referencia del Wayuunaiki
+**Estado:** 🟢 v0.2 desplegado (Ollama + HF) · borrador sin validar por hablantes · **Fecha:** Mayo 2026