ZyFalo/mabel-gemma4-e4b

Mabel — Asistente de Apoyo Emocional (Gemma 4 E4B fine-tune)

Mabel v1 es un fine-tune QLoRA de google/gemma-4-E4B-it orientado al acompañamiento emocional de estudiantes universitarios colombianos (20-26 años).

Proyecto de tesis — Universidad Manuela Beltrán (Colombia) — autor: William Andrés Peña Vargas (@ZyFalo).

⚠️ No es un reemplazo de atención psicológica profesional. Su función es acompañar, validar emocionalmente y derivar a recursos reales cuando sea necesario.

Detalles del modelo

Arquitectura

Datos extraídos del model card oficial de Google y verificados contra el metadata binario del GGUF (general.architecture = gemma4).

Uso efectivo del contexto en inferencia

El modelo soporta 128 K nativos en arquitectura, pero el contexto utilizable depende del flag --n_ctx del servidor y de la memoria disponible:

Para uso típico de Mabel (sesión emocional de 20-40 turnos cortos), `n_ctx 8192` es suficiente y eficiente.

Dataset

Total: 8.040 ejemplos de entrenamiento + 500 de evaluación. Todos con el system prompt B+ unificado (pieza crítica de la activación del LoRA).

Distribución exacta del train (medida sobre data/train.jsonl)

Fuentes EN (counselling real, NO traducido)

Decisión clave (D-016): NO se tradujeron los datasets EN al español. Gemma 4 es multilingüe (140+ idiomas) y aprende los patrones de counselling del inglés transfiriéndolos automáticamente al español durante inferencia (cross-lingual transfer validado empíricamente).

Fuente ES (sintético propio, generado y validado)

3 286 ejemplos (40% del train) generados durante 33 rondas iterativas documentadas en `docs/23-bitacora-generacion-sintetica.md`.

Pipeline de generación:

• —Orquestador: Claude Opus 4.7 — diseñaba el prompt de cada ronda, lanzaba agentes en paralelo, post-procesaba outputs
• —Generadores: 2-4 agentes Claude Sonnet 4.6 en paralelo por ronda — escribían JSONL con metodología Write directa
• —Extracción tolerante: json.JSONDecoder().raw_decode() con recuperación de ~87.5% incluso en outputs truncados
• —Total: 33 rondas (R1-R33) cubriendo conversación normal, crisis A/B/C/D, rechazo, identidad

Pipeline de validación y limpieza (también orquestado por Opus):

1. 1.Regex automática: barrido por patrones prohibidos (diagnóstico, bullets, headings, emojis, sermones, "-e" final indebido) → 0 violaciones al cierre
2. 2.Validación cualitativa estratificada (`docs/24`): lectura completa de 27 conversaciones representativas (3 por cada bucket de tema/complejidad)
3. 3.Validación específica de crisis (`docs/25`): auditoría híbrida (regex + lectura completa) de los 4 tipos A/B/C/D para garantizar derivación correcta (Línea 123, Línea 106, Línea 155, Bienestar UMB)
4. 4.Re-formateo iterativo: cuando una ronda no pasaba validación, se relanzaba con agente Sonnet correctivo de "reescritura quirúrgica" (no regeneración completa)

Eval set

500 ejemplos en data/eval.jsonl, estratificados con la misma proporción que el train, con holdout estricto (no overlap con train).

Disclaimer académico sobre el sintético

El dataset sintético ES fue generado con LLMs comerciales (Claude Opus 4.7 + Sonnet 4.6) bajo licencia de uso académico no-comercial. No se redistribuye públicamente por estar sujeto a los términos de uso de los proveedores de los modelos generadores y por contener fraseo clínico que debe ser auditado por profesional de salud mental antes de cualquier despliegue masivo.

Resultados (batería formal 12 turnos × 2 runs)

Limitaciones conocidas

• —R33 (identidad creador): cristalizó solo ~60%. Mabel a veces atribuye su creación a "Google" o al "equipo UMB" en lugar de William. → plan v1.1
• —D-020 (anti-listas): cristalización parcial; entre runs varía si responde lista o rechaza
• —Alucinación numérica ocasional: en recursos UMB puede inventar líneas de atención (mitigable con RAG futuro)
• —Dependencia del system prompt: requiere el B+ exacto para activación óptima (comportamiento estándar de LoRAs)

API pública disponible (Modal.com)

Mabel v1 está desplegado en producción como endpoint OpenAI-compatible servido por llama-server (llama.cpp oficial) sobre GPU T4 en Modal serverless con scale-to-zero.

POST https://williamandres1603--mabel-api-serve.modal.run/v1/chat/completions

Drop-in replacement para cualquier app que ya consuma la API de OpenAI: solo cambian 3 líneas (base_url, api_key, model).

Ejemplo con OpenAI SDK (Python)

from openai import OpenAI

client = OpenAI(
    base_url="https://williamandres1603--mabel-api-serve.modal.run/v1",
    api_key="not-used",   # llama-server no valida auth por defecto
)

SYSTEM_B_PLUS = """Te llamas Mabel, asistente de apoyo emocional para estudiantes universitarios colombianos de la UMB. Escucha activa: valida emociones primero y haz preguntas exploratorias para entender lo que pasa. Cuando tenga sentido, ofrece 1-2 sugerencias prácticas breves en prosa, sin imponer. No eres psicóloga profesional, no diagnosticas ni das planes terapéuticos. Tampoco resuelves tareas académicas, código, traducciones, resúmenes ni preguntas factuales: si te las piden, valida la emoción detrás y redirige sin sermonear. Responde en español colombiano, breve (máx 4-5 frases), conversacional, puede usar negrita y cursiva para énfasis, sin headings ni listas con bullets ni emojis. Si hay crisis (suicidio, autolesión), mantén la calma, valida, deriva a Línea 123, Línea 106, Línea 155 o Bienestar UMB y pregunta por persona de confianza."""

response = client.chat.completions.create(
    model="mabel-gemma4-e4b-Q4_K_M",
    messages=[
        {"role": "system", "content": SYSTEM_B_PLUS},
        {"role": "user", "content": "Hola, me siento mal últimamente"},
    ],
    temperature=0.7,
    max_tokens=500,
)
print(response.choices[0].message.content)

Ejemplo con curl

curl https://williamandres1603--mabel-api-serve.modal.run/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mabel-gemma4-e4b-Q4_K_M",
    "messages": [
      {"role": "system", "content": "Te llamas Mabel..."},
      {"role": "user", "content": "Hola"}
    ],
    "temperature": 0.7,
    "max_tokens": 200
  }'

Características operativas del endpoint

⚠️ Disclaimer académico sobre la API pública: el endpoint es público pero está destinado a uso académico para el proyecto de tesis (Universidad Manuela Beltrán). No use Mabel para diagnóstico clínico, atención de crisis sin supervisión profesional, ni despliegues comerciales sin auditoría psicológica previa. El presupuesto del endpoint es limitado ($30/mes free tier de Modal); abuso de tráfico puede agotarlo prematuramente.

Documentación técnica completa del hosting (8 bugs encadenados durante la implementación, decisiones de arquitectura, métricas medidas): `docs/29-hosting-modal.md`.

📘 Guía de integración paso a paso (cómo conectar Python/Node/PHP/React+FastAPI/cURL al endpoint, con system prompt literal, manejo de cold start, streaming, health check y checklist accionable): `docs/30-guia-integracion-api.md`.

Uso local (llama-cpp-python)

pip install llama-cpp-python[server]
python -m llama_cpp.server \
  --model gemma-4-E4B-mabel-Q4_K_M.gguf \
  --n_ctx 8192 \
  --n_gpu_layers -1 \
  --chat_format gemma

System prompt (CRÍTICO — no modificar)

El modelo fue entrenado con un system prompt fijo de 151 palabras ("B+"). Usarlo literal es lo que activa el comportamiento del LoRA — cambiarlo degrada notablemente la calidad de las respuestas (perdés activación de las reglas R28-R33 y del estilo conversacional breve). Está disponible como archivo aparte: `system_prompt.txt`.

Te llamas Mabel, asistente de apoyo emocional para estudiantes universitarios colombianos de la UMB. Escucha activa: valida emociones primero y haz preguntas exploratorias para entender lo que pasa. Cuando tenga sentido, ofrece 1-2 sugerencias prácticas breves en prosa, sin imponer. No eres psicóloga profesional, no diagnosticas ni das planes terapéuticos. Tampoco resuelves tareas académicas, código, traducciones, resúmenes ni preguntas factuales: si te las piden, valida la emoción detrás y redirige sin sermonear. Responde en español colombiano, breve (máx 4-5 frases), conversacional, puede usar negrita y cursiva para énfasis, sin headings ni listas con bullets ni emojis. Si hay crisis (suicidio, autolesión), mantén la calma, valida, deriva a Línea 123, Línea 106, Línea 155 o Bienestar UMB y pregunta por persona de confianza.

Parámetros de inferencia recomendados

Ejemplo de llamada OpenAI-compatible

import requests
SYSTEM = open("system_prompt.txt").read().strip()
r = requests.post("http://localhost:8000/v1/chat/completions", json={
    "model": "gemma-4-E4B-mabel-Q4_K_M",
    "messages": [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": "Hola, me siento muy mal últimamente"},
    ],
    "temperature": 0.7,
    "max_tokens": 1500,
})
print(r.json()["choices"][0]["message"]["content"])

Verificación

SHA256: 3d9ffb485a718d925915666b1151e25c0704bc6a1ca85ca77153d4e863237792

Licencia y términos

• —Modelo base Gemma 4: sujeto a Gemma Terms of Use de Google. Este fine-tune hereda esa licencia.
• —Pesos derivados: liberados públicamente para investigación académica (proyecto de tesis UMB). Cualquier uso debe respetar los Gemma Terms of Use heredados y el disclaimer clínico de esta tarjeta. No usar para diagnóstico clínico, atención a crisis sin supervisión profesional, ni despliegues comerciales sin auditoría psicológica previa.
• —Dataset sintético: generación asistida con LLMs comerciales; uso académico no-comercial.

Citar

@misc{pena_mabel_2026,
  author       = {Peña Vargas, William Andrés},
  title        = {Mabel: Asistente de Apoyo Emocional Fine-tuned de Gemma 4 E4B},
  year         = {2026},
  institution  = {Universidad Manuela Beltrán, Colombia},
  note         = {Tesis de pregrado},
  url          = {https://github.com/ZyFalo/Gemma4-Mabel}
}

Repositorio de proyecto

Documentación completa, decisiones, bitácoras y código de entrenamiento: https://github.com/ZyFalo/Gemma4-Mabel

Punto de entrada recomendado: `docs/26-memoria-proyecto.md`