Líder de delivery y transformación con IA. Más de 15 años al frente de programas grandes; además construyo y opero los sistemas de IA de abajo.

Casi todo el trabajo con IA se muestra como una demo. Este es un portfolio personal con algunos de los proyectos que hice, y qué pasó después.

Son proyectos personales, hechos y operados por mi cuenta para mostrar mis skills en IA aplicada: no son trabajos para clientes. Cada uno está documentado desde su propio repositorio, con el problema, el alcance, la arquitectura, las decisiones de diseño y los resultados.

Foto de Jorge Roberts
6iniciativas documentadas
4en producción
433pedidos a LLMs en 30 días
2.0Mtokens en 30 días

Iniciativas

Proyectos personales. Primero los seleccionados; el resto está en Todas.

Bot · desde 2026-07 · En producción

HealthBot

Coach personal de salud por Telegram que registra comida, entrenamiento y sueño en lenguaje natural o por foto, y genera planes diarios, semanales y mensuales con LLM, RAG sobre evidencia citada y guards determinísticos sobre cada número.

  • Reportes en cascada mensual, semanal y diario que ajustan solos los targets de nutrición, sueño, entrenamiento y suplementación; 67 reportes generados y persistidos.
  • RAG sobre 589 videos y 17.588 fragmentos, con un índice vectorial por fuente y principios destilados cruzando fuentes.
  • 70 pruebas de guards determinísticos, cada una construida desde un caso real que se había colado en producción.
  • Visión de comida rediseñada para que el modelo solo identifique y pese; el código calcula, y la misma comida da el mismo número por foto y por texto.
  • Trazas de punta a punta (bot, gateway, proveedor) de cada corrida y cada reporte.
  • Eval de recuperación con dataset congelado: encontró que una fuente entera no llegaba a los reportes y el fix subió hit@5 de 0,64 a 0,74.
Escala
589 videos y 17.588 fragmentos indexados; bot, API y una app Android
LLM, 30 días
120 pedidos, 350.507 tokens
Verificado
2026-10-30
CI
pasa (2026-11-20)

rag · vision · structured-extraction · llm-reports · deterministic-guards · tier-escalation · observability · node · sqlite · sqlite-vec · express · telegram · python · docker · opentelemetry

Resumen técnico
  • Plataforma: Node.js en Docker; bot de Telegram por long polling (node-telegram-bot-api), API HTTP con Express (Bearer con falla cerrada y tope de intentos) para la app Android y el receiver de Health Connect, y un scheduler de crons en hora local.
  • Datos: SQLite con better-sqlite3 (38 tablas) y sqlite-vec para tres índices vectoriales, uno por fuente del corpus; migraciones al arrancar.
  • LLM: el texto pasa por el gateway propio con su key y su política (llm-policy.yaml), vía @homelab/llm-client. Tiers: tier-2 para chat, tier3-tools para el briefing diario, tier3-reasoning para semanal y mensual, tier-vision para fotos de comida. Embeddings con NVIDIA NIM y visión de respaldo con Google Gemini.
  • RAG: ingesta productor-consumidor de transcripciones de YouTube (Python + Node), embeddings, recuperación por fuente y principios destilados; eval con dataset congelado (hit@5).
  • Integraciones: Telegram, Health Connect (vía la app Android), YouTube (transcripciones), LLM Gateway.
  • Observabilidad: OpenTelemetry de punta a punta (bot, gateway, proveedor) hacia Jaeger y Langfuse.
  • Calidad: 70 tests de guards determinísticos construidos desde casos reales, calibración de fotos, macros y RAG con herramientas propias.
  • Deploy: servicio del docker-compose del homelab, solo por script, con imagen de rollback tagueada.
Problema y alcance

Problema

Seguir un plan de nutrición y entrenamiento exige registrar mucho (comidas, agua, cargas, peso, sueño) y, sobre todo, cruzar esos datos para decidir qué ajustar. Las apps comerciales registran pero no razonan, y un chat genérico con un LLM razona pero no recuerda, inventa números y no tiene los datos del reloj.

HealthBot es un coach personal de salud: se le habla en lenguaje natural por Telegram (o se le manda una foto del plato), registra lo que corresponde, y todos los días arma un plan contra el historial real, con evidencia citada de un corpus de divulgación científica. La premisa de diseño es que el LLM aporta criterio, pero todo número que se puede calcular o verificar lo calcula y lo verifica el código.

Alcance

  • Registro por lenguaje natural, por comandos y por foto: comida, agua, peso y medidas, entrenamientos (series, reps, carga, RIR, drop sets y super series), suplementos, check-in subjetivo, laboratorio.
  • Ingesta de datos del reloj vía Health Connect (sueño, HRV, FC, pasos, calorías, sesiones de ejercicio).
  • Estimación de macros por texto y por foto (plato o etiqueta nutricional).
  • Reportes en cascada mensual → semanal → diario que ajustan targets.
  • Rutina dinámica con progresión de cargas determinística y mesociclos.
  • RAG sobre transcripciones de Huberman Lab, Dr. La Rosa y una fuente de respaldo, con principios destilados.
  • API HTTP de lectura y escritura para la app.
  • Trazas de punta a punta de cada corrida.
Arquitectura y decisiones

Diagrama

flowchart LR
  user[Usuario] -->|chat y fotos| tg[Telegram]
  tg --> bot[Bot y handlers]
  app[HealthApp Android] -->|API con token| api[API HTTP]
  hc[Health Connect del teléfono] --> app
  bot --> guards[Guards determinísticos]
  api --> guards
  cron[Scheduler de reportes] --> guards
  guards --> db[(SQLite + índices vectoriales)]
  bot --> rag[RAG sobre corpus de videos]
  cron --> rag
  api --> rag
  rag --> db
  bot --> gw[LLM Gateway]
  cron --> gw
  api --> gw
  rag -.->|embeddings, hoy directo| emb[Proveedor de embeddings]
  bot -.->|visión de respaldo, hoy directo| vis[Proveedor de visión]
  bot --> otel[Trazas OpenTelemetry]
  gw --> models[Modelos locales y gratuitos por tier]

Decisiones de diseño

  • El prompt pide, el guard garantiza. Todo lo que se puede verificar contra el texto del usuario o contra un rango plausible se verifica en código; al LLM se le deja el criterio. Cada guard nació de un caso real y tiene su prueba.
  • El modelo identifica y pesa; el código calcula. Una foto dice qué hay, no cuánto pesa: la visión devuelve ítems y gramos, y las calorías salen de la misma función que usa el camino de texto.
  • Directives máquina-legibles con extracción de respaldo. Los reportes emiten AJUSTE, RUTINA y MESOCICLO; si el modelo no los emite inline, una llamada acotada los extrae del análisis ya escrito.
  • Cascada con un solo escritor por campo. Mensual y semanal escriben el ajuste; el diario solo lee con COALESCE. El último que corre pisa.
  • Rotación real en vez de calendario. Qué toca hoy sale del historial de entrenamientos, con detección de parate.
  • Un índice vectorial por fuente. Las distancias entre índices no son comparables; separados, cada fuente puede cambiar de modelo de embeddings sin romper las otras.
  • Cliente flaco. La app no tiene lógica ni keys de LLM: si app y bot pueden discrepar sobre un número, el cálculo está en el lugar equivocado.
  • Rechazar antes que mandar basura. Un reporte que no pasa la validación se reintenta o no se envía.
  • Fechas en un único módulo. El container corre en UTC y el día se calcula siempre en hora local, en un solo lugar.
Resultados
  • En uso diario desde julio de 2026, con 67 reportes de la cascada generados y persistidos (49 diarios, 15 semanales, 3 mensuales) y ajustes de targets aplicados automáticamente.
  • Corpus de 589 videos y 17.588 fragmentos indexados en tres índices vectoriales separados por fuente.
  • 70 pruebas automáticas de guards, cada una construida a partir de un caso real que se había colado en producción.
  • La misma comida da el mismo número por foto y por texto: la visión dejó de estimar calorías y solo identifica y pesa.
  • La carga de comida por texto desde la app bajó de hasta 2 minutos a menos de un segundo al saltear el clasificador general.
Evidencia

src/shared/macros.js, línea 301

export function calcularDesdeItems(parsed, desc, origen = 'texto') {
  // Lo que el usuario conto explicitamente no se estima: se multiplica. Ver
  // cantidadesExplicitas() — "dos huevos" son 2 x 55 g, no lo que el modelo recuerde.
  const explicitas = cantidadesExplicitas(desc);

  const items = (Array.isArray(parsed?.items) ? parsed.items : [])
    .filter(i => Number.isFinite(i?.gramos) && i.gramos > 0)
    // Antes de cualquier cuenta: si el peso es en realidad una cantidad, se corrige.
    .map(i => ({ ...i, gramos: pesoDeUnidades(i?.nombre, i.gramos) }))
    .map(i => {
      const match = explicitas.find(e => referenciasMencionadas(i?.nombre || '')[0]?.id === e.ref.id);
      if (!match) return i;
      const exacto = match.cantidad * match.ref.unit_grams;
      if (Math.abs(exacto - i.gramos) / exacto > 0.1) {
        logger.info({ item: i.nombre, modelo: i.gramos, contado: exacto, cantidad: match.cantidad },
          'el usuario dijo la cantidad: el peso sale de multiplicar, no de estimar');
      }
      return { ...i, gramos: exacto, _contado: true };
    })
El modelo identifica y pesa; el código calcula. Si la persona dijo la cantidad, el peso sale de multiplicar, no de estimar.

Infraestructura · desde 2026-06 · En producción

LLM Gateway

Gateway propio que enruta los pedidos de varias apps a modelos locales y gratuitos por tiers de capacidad, con failover, guardrails por app y trazas de punta a punta.

  • 8 grupos de modelos sobre 5 proveedores, sin costo por llamada.
  • Cuatro retiros de modelos absorbidos cambiando solo config, sin tocar ninguna app.
  • Guardrails contra prompt injection, con la política de cada app declarada y versionada en su propio repo.
  • Trazas de punta a punta (app, gateway, proveedor) que permitieron medir y corregir un truncado silencioso.
Escala
8 grupos de modelos sobre 5 proveedores
LLM, 30 días
433 pedidos, 1.965.099 tokens
Verificado
2026-10-30
CI
pasa (2026-11-20)

model-routing · failover · guardrails · prompt-injection-defense · observability · python · litellm · postgres · redis · docker · opentelemetry

Resumen técnico
  • Plataforma: LiteLLM Proxy (API compatible con OpenAI) en Docker, con un callback propio en Python (async_pre_call_hook) que aplica la política de cada key antes de enrutar.
  • Proveedores y modelos por tier: Ollama local (qwen2.5:0.5b, llama3.2:1b) para clasificación barata; Groq (gpt-oss-20b, gpt-oss-120b, qwen3.6-27b para visión); NVIDIA NIM (llama-3.1-8b, nemotron-3-nano-30b-a3b para function calling, nemotron-3-ultra-550b-a55b para razonamiento, llama-3.2-11b-vision, nemotron-3-embed-1b para embeddings); Google Gemini (3.6-flash); OpenRouter (llama-3.3-70b:free).
  • Datos: PostgreSQL 16 para virtual keys, metadata de política y spend logs; Redis como cache de respuestas (TTL 1 h).
  • Gobierno: una virtual key por app; tools/policy-sync lee el llm-policy.yaml versionado en cada repo y lo aplica a su key (timeout, sanitize, tools, purpose, RPM/TPM). Fallbacks filtrados por key; grupos solo-públicos con 403 si no están habilitados.
  • Observabilidad: OpenTelemetry (OTLP) hacia un collector propio con cola persistente, que reparte a Jaeger (local, Badger, 30 días) y Langfuse Cloud.
  • Clientes: paquete compartido @homelab/llm-client (Node.js) usado por las apps del homelab.
  • Calidad: tests unitarios de guardrails dentro de la imagen y suite end-to-end con LiteLLM aislado, Postgres y un proveedor eco propio, sin consumir cuota.
  • Deploy: imagen propia construida desde el repo, servicio del docker-compose del homelab; se prueba en una instancia aparte y el rollback es volver la config al commit anterior.
Problema y alcance

Problema

Varios bots y apps personales necesitan LLMs con requisitos distintos (tool use, razonamiento, visión, embeddings, datos sensibles o públicos) y sin pagar por llamada. Hablar directo con cada proveedor dispersa las API keys, no deja medir consumo ni calidad, y cada vez que un proveedor gratuito retira un modelo se rompe una app distinta.

Alcance

  • Una API compatible con OpenAI para todas las apps.
  • Tiers por capacidad, cada uno con varios proveedores en orden y failover automático.
  • Una virtual key por app, con modelos permitidos, límites y una política de guardrails propia, declarada en el repo de la app.
  • Guardrails genéricos contra prompt injection aplicados en el proxy.
  • Cache, trazas OpenTelemetry y registro de consumo.
Arquitectura y decisiones

Diagrama

flowchart LR
  subgraph apps[Apps]
    hb[healthbot]
    ad[ai-digest]
    hub[hub]
    wa[Walle]
  end
  subgraph gw[LLM Gateway]
    g[Guardrails<br/>política por key]
    r[Router LiteLLM<br/>tiers + failover]
    c[(Redis cache)]
    db[(Postgres<br/>keys + consumo)]
  end
  hb & ad & hub & wa -->|virtual key| g --> r
  r --- c
  g --- db
  r --> ol[Ollama local]
  r --> groq[Groq]
  r --> nim[NVIDIA NIM]
  r --> gem[Gemini]
  r --> orr[OpenRouter]
  r -.OTLP.-> otel[OTel Collector] --> jg[Jaeger] & lf[Langfuse]

Decisiones de diseño

  • Gateway único en vez de un SDK por proveedor: los retiros de modelos se arreglan en un solo archivo y las apps no cambian.
  • Tiers por capacidad, no por proveedor: la app pide "razonamiento", no "NVIDIA".
  • El largo del input lo decide cada app: el gateway primero truncaba en silencio (rompía prompts sin que nadie lo notara), después rechazaba con 413; finalmente el tope pasó a cada proyecto, que conoce el tamaño legítimo de sus prompts.
  • El gateway impone la duración máxima por key: una app no puede pedir más tiempo que el que su política permite.
  • Escape de tags por allowlist: se escapa todo < que pueda abrir un tag y pasan ->, >99 y <100.
  • Grupo aparte para datos públicos: permite usar proveedores que loguean sin exponer datos personales.
  • Guardrails en dos capas (ADR 0001): política versionada en cada app, controles específicos en el código de cada app.
Resultados
  • 8 grupos de modelos sobre 5 proveedores, todos gratuitos o locales.
  • Sobrevivió a cuatro retiros silenciosos de modelos (NVIDIA, Groq, OpenRouter) cambiando solo config, sin tocar las apps.
  • Con trazas se detectó y corrigió un truncado silencioso del guardrail que le cortaba a una app hasta el 65% de su prompt más largo.
  • Una sola traza de punta a punta (app → gateway → proveedor) en Jaeger y Langfuse.
Evidencia
Línea de tiempo de una traza con spans de dos servicios, la app y el gateway
Traza real de un reporte diario: la app abre la traza, el gateway se suma a la misma y el primer intento contra un proveedor falla (marca roja) antes de que el router lo resuelva. Los 1,8 minutos son del modelo de razonamiento que arma el reporte, que corre en segundo plano.

litellm/guardrails.py, línea 116

def _restrict_fallbacks(fallbacks, key_models):
    """Cadena de fallbacks del router limitada a lo que la key puede usar.

    key_models vacio = la key puede usar cualquier grupo, salvo los solo-publicos.
    Devuelve la lista en el mismo formato del router ([{origen: [destinos]}]).
    """
    allowed = set(key_models or [])
    public_key = bool(allowed & PUBLIC_ONLY_GROUPS)
    ok = (lambda m: m in allowed) if allowed else (lambda m: m not in PUBLIC_ONLY_GROUPS)
    out = []
    for item in fallbacks:
        if not isinstance(item, dict):
            continue
        for src, targets in item.items():
            if not ok(src):
                continue
            keep = [t for t in (targets or []) if ok(t) and (public_key or t not in PUBLIC_ONLY_GROUPS)]
            if keep:
                out.append({src: keep})
    return out
La cadena de fallbacks se filtra por pedido: un fallo nunca termina en un modelo que la key no tiene habilitado.

Servicio · desde 2026-10 · En desarrollo

AI Digest

Newsletter semanal de IA armada por un flujo agéntico de seis etapas, desde la lectura de más de 25 fuentes hasta un mail con hasta 20 noticias validadas.

  • Flujo de seis etapas donde el código valida y el modelo solo decide lo que requiere juicio.
  • De unas 260 piezas por semana a un máximo de 20, sin ninguna URL ni cifra que no esté en la fuente.
  • Modelo por etapa elegido midiendo contra un fixture fijo, no por intuición.
  • Descarga de páginas con protección SSRF y alta de fuentes nuevas solo con aprobación humana.
  • 28 tests sin red, incluido un extremo a extremo con un LLM falso.
Escala
Más de 25 fuentes y hasta 20 noticias por edición
LLM, 30 días
220 pedidos, 1.600.463 tokens
Verificado
2026-10-29
CI
pasa (2026-11-20)

agentic-pipeline · curation · summarization · source-discovery · output-validation · node · nunjucks · readability · docker

Resumen técnico
  • Plataforma: Node.js en un contenedor efímero por corrida (imagen propia), disparado por cron los lunes; CLI con lock, --dry-run, --since y --month.
  • Fuentes: más de 25 entre feeds RSS/Atom, Hugging Face, arXiv y GitHub, declaradas en un registro versionado (sources.yaml).
  • Procesamiento: Mozilla Readability para el texto completo, descargas con protección SSRF propia (solo 80/443, sin IPs privadas, revalida redirects), filtros por fecha y duplicados.
  • LLM: todo por el gateway propio con la key app-ai-digest; tier-2 y tier3-public (grupo solo para datos públicos). Streaming, extracción y validación de JSON por esquema, reintentos ante salida cortada y tope de 45.000 caracteres por pedido.
  • Prompts: skill versionada por etapa (triage, enrich, compose, discover), con la regla de que el contenido externo va siempre entre etiquetas y nunca en el system.
  • Validación determinística: URLs y cifras contrastadas contra la entrada; topes de cantidad por sección; modo degradado.
  • Entrega: render HTML con Nunjucks, envío por SMTP a destinatarios fijos, archivo de cada edición y aviso de falla por el notificador del homelab (Telegram).
  • Calidad: 28 tests con node --test, sin red, incluido un extremo a extremo contra un fixture con LLM falso.
Problema y alcance

Problema

Mantenerse al día en IA exige leer muchas fuentes dispersas, y la mayoría de lo que se publica es ruido o repetición. El objetivo es que todos los lunes a la mañana llegue un mail con formato de newsletter ("Weekly report") con hasta 20 noticias de la semana, cada una con link a la fuente original y una lectura de por qué importa.

Foco editorial: novedades con valor práctico, no "noticias de IA". Prioriza modelos nuevos (capacidades y precio), papers y benchmarks, prácticas y metodologías de trabajo con agentes, skills, seguridad de agentes y repositorios. Descarta rondas de inversión, movimientos de personas, polémicas y anuncios corporativos sin sustancia técnica.

Objetivo secundario: que el proyecto sea un ejemplo práctico de un flujo agéntico cerrado, con una skill versionada, ruteo por niveles en LiteLLM, validación de salida y observabilidad.

Alcance

Incluye: el job semanal y el mensual, el modo --dry-run en los dos, la corrida manual de una semana (--since) o de un mes (--month) y el archivo de cada edición.

No incluye

  • LinkedIn y X. No ofrecen feed y scrapearlos va contra sus términos.
  • Fuentes pagas o detrás de login.
  • Republicar textos completos.
  • Agregar fuentes sin aprobación humana.
Arquitectura y decisiones

Diagrama

flowchart LR
  subgraph semanal[Job semanal]
    c[collect<br/>feeds, HF, arXiv, GitHub] --> t[triage<br/>prefiltro por lotes + selección]
    t --> e[enrich<br/>texto completo + datos con cita]
    e --> co[compose<br/>newsletter en JSON]
    co --> v[validate<br/>URLs, cifras, topes]
    v --> r[render + envío]
  end
  subgraph mensual[Job mensual]
    d[discover<br/>fuentes citadas por el registro]
  end
  reg[(sources.yaml)] --> c
  r -. links y salud .-> d
  d -. candidatas, alta humana .-> reg
  t & e & co & d -->|key propia| gw[LLM Gateway]
  r --> mail[Mail semanal]
  r -. solo fallas .-> n[Notificador]

Decisiones de diseño

  • Flujo agéntico cerrado en seis etapas, con código donde se puede verificar (fetch, filtros, validación, render) y modelo solo donde hace falta juicio (selección, lectura, redacción).
  • La validación decide, no el modelo: ninguna URL ni cifra llega al mail si no está en la entrada.
  • Descubrimiento por citas entre fuentes del registro, sin búsqueda web, con alta humana: evita el envenenamiento del registro.
  • Modelo por etapa elegido midiendo contra un fixture fijo: el prefiltro y compose pasaron al razonador porque con el modelo generalista la salida llegaba cortada.
  • Modo degradado: si una etapa falla, la edición sale reducida y avisa, en vez de no salir.
Evidencia
Primera pantalla de la newsletter semanal con destacados y la sección de modelos
Edición real generada por el flujo: cada noticia con su fuente; ninguna URL ni cifra que no esté en la entrada. Es la Nº 35 porque la numeración continúa la de la edición de referencia que se usó como modelo.

src/validate.js, línea 38

function keepSupported(text, pool) {
  let dropped = 0;
  const kept = sentences(text).filter((s) => {
    const ok = significantNumbers(s).every((tok) => [...readings(tok)].some((r) => pool.has(r)));
    if (!ok) dropped++;
    return ok;
  });
  return [kept.join(' '), dropped];
}
Validación de cifras: una oración con un número que no aparece en las fuentes se descarta antes del envío.

Servicio · desde 2026-06 · Discontinuado

Personal CRM

CRM personal que consolidó una agenda de miles de contactos y la validó por conversación en WhatsApp, con clasificación de intents por LLM y revisión humana en el circuito.

  • Consolidó unos 12.500 contactos de cuatro fuentes, con deduplicación asistida por LLM en 54 lotes revisables.
  • Validación conversacional con 15 intents, allowlist de salida, umbral de confianza y escalación humana.
  • Operó un evento real de más de cien invitados con invitación, RSVP conversacional y listado final.
  • Cuatro capas independientes contra envíos indebidos más un kill-switch global fail-closed.
Escala
Unos 12.500 contactos consolidados de 4 fuentes; un evento real operado de punta a punta
LLM, 30 días
1 pedidos, 481 tokens

intent-classification · llm-dedup · human-in-the-loop · confidence-escalation · output-allowlist · speech-to-text · nodejs · sqlite · express · whatsapp-web.js · puppeteer · telegram-bot-api · ollama · docker

Resumen técnico
  • Plataforma: Node.js 22 en Docker con Chromium, orquestado por ticks; Review UI con Express y una SPA para la revisión humana.
  • Canales: WhatsApp con dos instancias de whatsapp-web.js (Puppeteer) y un único punto de salida que chequea el kill-switch; Telegram con un bot propio (fetch nativo) para escalaciones bidireccionales.
  • Fuentes de contactos: importadores de vCard, export de WhatsApp, Instagram y LinkedIn, con normalización y deduplicación asistida por LLM en lotes revisables.
  • Datos: SQLite con 22 migraciones, máquina de estados con audit log y backup rotativo.
  • LLM: clasificación de intents y de RSVP con modelos locales (Ollama) y escalación a un modelo más capaz si la confianza es baja; sugerencia de FAQ por el gateway propio.
  • Audio: transcripción con Whisper para clasificar notas de voz.
  • Guardrails: sanitizado y delimitación del input, allowlist de intents, umbral de confianza 0,75 con escalación, textos de salida fijos o aprobados y kill-switch fail-closed.
Problema y alcance

Problema

Una agenda personal acumulada durante más de diez años (unos 12.500 contactos repartidos entre el teléfono, WhatsApp, Instagram y LinkedIn) no sirve para lo más básico: saber a quién se puede invitar a un encuentro. Hay duplicados, números que cambiaron de dueño, contactos sin teléfono y ninguna señal de qué relaciones siguen vivas. Depurarla a mano, contacto por contacto, no escala; automatizarla sin cuidado significa mandarle mensajes equivocados a gente real con el número personal del dueño.

El proyecto buscó resolver las dos cosas a la vez: consolidar y priorizar la agenda, y validar por conversación si cada contacto sigue vigente, para después invitar a eventos solo a gente confirmada. Siempre con un humano en el circuito para los casos que la máquina no puede resolver bien.

Alcance

  • Ingesta y consolidación de contactos de varias fuentes, con deduplicación asistida.
  • Scoring de relevancia y segmentación por tier.
  • Validación conversacional por WhatsApp ("¿seguís con este número?") con clasificación de respuestas.
  • Gestión de eventos: invitaciones, RSVP conversacional, recordatorios y listado final.
  • Panel web de revisión humana y escalación por Telegram.
Arquitectura y decisiones

Diagrama

flowchart LR
  subgraph fuentes[Fuentes]
    vcf[vCard] & wa_exp[Export WhatsApp] & ig[Instagram] & li[LinkedIn]
  end
  fuentes --> imp[Importadores + normalización]
  imp --> dedup[Dedup asistida por LLM]
  dedup --> rev_dedup{{Revisión humana de merges}}
  rev_dedup --> db[(SQLite)]
  db --> score[Scoring A/B/C]
  score --> review{{Review UI: aprobar contactos}}
  review --> tick[Orquestador por ticks]
  tick --> gates[Gates: texto aprobado, anti-duplicado, rate limit]
  gates --> ks{Kill-switch global}
  ks -->|habilitado| wa[WhatsApp emisor / receptor]
  wa -->|respuestas de terceros| cls[Clasificador de intents]
  cls --> llm[LLM local con escalación]
  cls -->|intent en allowlist y confianza alta| sm[Máquina de estados]
  cls -->|baja confianza o intent sensible| esc[Escalación a Telegram]
  esc --> human{{Dueño responde}}
  human --> wa
  sm --> db
  sm --> events[Eventos: invitación, RSVP, listado final]
  events --> gates

Decisiones de diseño

  • Cliente no oficial de WhatsApp en vez de la API oficial. La API oficial exigía migrar el número personal a una cuenta de empresa y solo permite iniciar conversaciones con plantillas aprobadas. El cliente no oficial se operó con volumen bajo, jitter, warmup, horario y auto-reducción ante señales de bloqueo.
  • Estrategia de dos números. El número con historial valida (los contactos lo reconocen) y entrega la vCard de un número nuevo dedicado a eventos.
  • Defensa en profundidad contra envíos indebidos. Cada capa asume que las anteriores pueden fallar: guard de ticks, reclamo atómico por estado, verificación por contenido ya enviado y gate de texto aprobado, más un kill-switch global fail-closed en el único punto de salida hacia WhatsApp.
  • LLM para clasificar, nunca para redactar al contacto. El modelo elige un intent de una lista cerrada; la respuesta sale de textos fijos o aprobados por el dueño.
  • Humano en el circuito por diseño. Umbral de confianza, intents que escalan siempre, cola de revisión y aprobación previa de contactos y textos.
  • Escalaciones sin datos personales. El canal de escalación solo ve un identificador; el nombre se resuelve en la base local.
  • Toda transición de estado por un único punto con audit log, para poder reconstruir por qué un contacto quedó donde quedó.
  • Local-first con escalación. Clasificación con modelo local y reintento con uno más capaz si la confianza es baja.
  • Privacidad. Solo contactos propios; los datos de terceros se procesaron en el servidor propio y ni la base ni las sesiones entraron nunca a git.
Resultados
  • Se consolidó una agenda de unos 12.500 contactos de cuatro fuentes, con deduplicación asistida por LLM en 54 lotes revisables y priorización A/B/C.
  • El pipeline se usó en un evento real: más de cien invitados, invitaciones con flyer, RSVP conversacional y listado final entregado al organizador.
  • La protección contra envíos indebidos quedó en cuatro capas independientes más un freno global: guard anti-solapamiento de ticks, reclamo atómico por estado, verificación por contenido exacto ya enviado, gate de texto aprobado y kill-switch fail-closed que cubre todos los caminos de salida.
  • Mover la generación de FAQ del modelo local al gateway bajó el tiempo de respuesta de 96 segundos a unos 4,5 segundos para 9 entradas completas.
Evidencia

src/shared/kill_switch.js, línea 23

export function isOutboundEnabled() {
  try {
    const db = getDb();
    const row = db.prepare(`SELECT enabled FROM system_flags WHERE key = ?`).get(KEY);
    return !!row && row.enabled === 1;
  } catch (err) {
    // Tabla no existe todavía, DB no disponible, lo que sea — fail-closed.
    logger.warn({ module: 'kill_switch', err: err.message }, 'No se pudo leer system_flags — fail-closed (deshabilitado)');
    return false;
  }
}
Único punto de salida hacia los contactos: si el flag no existe o no se puede leer, no sale nada (fail-closed).

App móvil · desde 2026-08 · En producción

HealthApp

App Android nativa que muestra y registra la salud por área sobre la API del bot, con sync de Health Connect, cola offline y notificaciones nativas, sin lógica de negocio ni LLM en el teléfono.

  • Cliente nativo por áreas de la salud sobre la misma API del bot, sin cálculos duplicados ni keys de LLM en el teléfono.
  • Reemplazó a dos apps con una sola al absorber el sync de Health Connect.
  • Cola de escritura offline con id de request estable y cache de lectura, para no perder ni duplicar registros sin conexión.
  • Notificaciones nativas por polling, sin Firebase ni infraestructura nueva.
  • 36 tests unitarios de red, cola y transporte contra un servidor HTTP simulado.
Escala
App Android nativa con 36 tests
CI
pasa (2026-11-20)

food-photo-estimation · rag-chat · llm-reports · kotlin · jetpack-compose · material3 · workmanager · health-connect · okhttp

Problema y alcance

Problema

Un bot de Telegram sirve para conversar y registrar, pero es malo para ver: no hay gráficos, no hay estado de un vistazo y saber "cómo vengo esta semana" obliga a releer una pared de texto. Además, los datos del reloj necesitaban una segunda app solo para sincronizar.

HealthApp es un cliente nativo sobre el mismo backend del bot, organizado por las áreas reales del problema, que además es la única dueña de la lectura de Health Connect. No reemplaza al bot: Telegram sigue para conversar.

Alcance

  • Lectura por área de lo que calcula healthbot, con gráficos propios.
  • Registro determinístico (agua, peso, medidas, entrenamiento, suplementos) y registro de comida por foto o texto.
  • Sync de Health Connect al servidor (absorbió a healthconnect-bridge).
  • Notificaciones nativas espejo de los avisos del bot.
  • Funcionamiento offline: cola de escritura y cache de lectura.
Arquitectura y decisiones

Diagrama

flowchart LR
  user[Usuario] --> ui[Pantallas Compose por área]
  watch[Reloj] --> hc[Health Connect]
  hc --> sync[Worker de sync]
  ui --> client[Cliente de API con cache]
  ui --> queue[Cola de escritura offline]
  ui --> photo[Worker de subida de fotos]
  queue --> transport[Transporte con fallback de URLs]
  client --> transport
  photo --> transport
  sync --> transport
  notif[Worker de notificaciones] --> transport
  transport -->|token| api[API de HealthBot]
  api --> brain[Lógica, base de datos y LLM en el servidor]

Decisiones de diseño

  • Cliente flaco, servidor gordo. La base del servidor es la única fuente de verdad, los cálculos viven en el servidor y la app pide criterios en vez de inventarlos.
  • Organizada por área de la salud, no por tipo de vista. Lo que se mira junto está junto.
  • Una sola app dueña de Health Connect. Dos apps leyendo lo mismo duplicaban filas y duplicaban fricción.
  • Lo determinístico no pasa por un LLM. "Ayer comiste menos, hoy sumá la diferencia" es una resta: meterle un modelo agrega latencia y variabilidad a cambio de nada. Lo mismo para el ruteo de notificaciones.
  • Polling en vez de push con Firebase. Para un usuario y avisos cuya urgencia se mide en horas, un worker periódico evita una cuenta, un proyecto y un servicio externo más.
  • Ack después de mostrar. Repetir un aviso molesta; perderlo hace que el sistema no sirva.
  • Fallback de red solo ante falla de conexión. Si el servidor contestó, aunque sea con error, no se prueba otra ruta.
  • Gráficos sin ceros inventados. Un día sin registro no es un día en cero.
Resultados
  • En uso diario desde agosto de 2026; reemplazó a dos apps (lectura y sync) con una sola.
  • Ningún cálculo duplicado entre app y bot: los números de la app y de Telegram salen de la misma función del servidor.
  • Registros offline que se reintentan solos, con id estable para no duplicar al reintentar.
  • 36 tests unitarios de red, cola offline y transporte contra un servidor HTTP simulado.
  • Sync automático de Health Connect funcionando después de diagnosticar en el dispositivo real dos causas raíz que lo tenían 17 días sin ejecutarse.

Infraestructura · desde 2026-06 · En producción

Infra homelab

Servidor propio que corre todos los proyectos en contenedores, con SSO de dos factores, acceso remoto por VPN, backups cifrados offsite y observabilidad de punta a punta.

  • 16 servicios en contenedores sobre un único servidor de 8 GB de RAM, separados en tres redes aisladas.
  • Un solo login de dos factores (Google más TOTP propio) para todos los paneles internos.
  • Una única superficie pública protegida por token; todo lo demás solo por VPN.
  • Backups cifrados local y offsite con verificación de integridad; el snapshot bajó de 2-3 GB a unos 58 MB al respaldar solo lo irreproducible.
  • Trazas OpenTelemetry de punta a punta con un collector propio y cola persistente.
LLM, 30 días
89 pedidos, 13.103 tokens
Verificado
2026-10-30

self-hosted-llm · llm-gateway-hosting · observability · ubuntu · docker · docker-compose · nginx · tailscale · restic · backblaze-b2 · opentelemetry · jaeger · netdata · node

Problema y alcance

Problema

Un desarrollador con varios proyectos personales y de clientes (bots, APIs, sitios, un gateway de LLM) necesita correrlos 24/7 sin pagar hosting por proyecto, con acceso seguro desde cualquier lado, backups que realmente se puedan restaurar y visibilidad de qué está pasando. Sin una base común, cada proyecto resolvía por su cuenta la exposición, los secretos y los backups, y nadie notaba cuando algo dejaba de funcionar.

Arquitectura y decisiones

Diagrama

flowchart LR
  inet((Internet))
  tnet((VPN mesh<br/>Tailscale))
  lan((LAN de casa))

  subgraph host[Servidor Ubuntu]
    funnel[Funnel público]
    serve[Serve solo VPN]

    subgraph net_public[red pública]
      vw[Vaultwarden]
    end

    hub[Hub SSO<br/>Google + TOTP]
    site[Sitio estático del portfolio]

    subgraph net_ai[red IA]
      hb[healthbot]
      gw[LLM Gateway<br/>litellm + postgres + redis]
      oll[Ollama]
      otel[OTel Collector]
      jae[Jaeger]
    end

    subgraph outside[Fuera de Docker]
      walle[OpenClaw / Walle]
      nd[Netdata]
    end

    bk[backup restic]
    disk[(disco único<br/>prod + backup local)]
  end

  b2[(Backblaze B2)]
  lf[Langfuse Cloud]
  prov[Proveedores LLM gratuitos]

  inet --> funnel --> site
  funnel -->|token Bearer| hb
  tnet --> serve --> walle
  tnet --> hub
  tnet --> vw
  tnet --> hb
  lan --> hb

  hub --> gw
  hub --> oll
  hub --> nd
  hb --> gw
  gw --> oll
  gw --> prov

  hb & gw --> otel --> jae
  otel --> lf

  bk --> disk
  bk -->|cifrado| b2

Decisiones de diseño

  • Un solo compose para todo: un servidor, un dueño; simplifica operación y backups a costa de acoplar los ciclos de vida (un up mal dado recrea todo).
  • Redes separadas por función: las apps que consumen LLM no ven los servicios web ni el proyecto del cliente; el hub es el único puente, así un compromiso de un servicio web no llega directo al gateway.
  • VPN en lugar de exposición pública: todo acceso remoto pasa por la VPN mesh; la única excepción es la API que necesita la app móvil fuera de casa, con token propio.
  • SSO propio con segundo factor independiente de Google: si se compromete la cuenta de Google, igual hace falta el TOTP.
  • Backup de lo irreproducible, no del working tree: se respalda la historia completa de los repos, las bases de datos y los secretos; el código desplegado se reconstruye desde git. Bajó el snapshot de gigabytes a decenas de megabytes y permitió subir todo offsite.
  • Offsite en la nube en vez de disco frío: el disco externo murió; un proveedor de object storage cifrado reemplaza la copia offline sin hardware nuevo.
  • Observabilidad con collector intermedio: las apps exportan a un único collector que decide destinos (local y cloud), con cola persistente para no perder trazas si un destino cae.
Notificador

Un solo punto de salida para avisos operativos: scripts/notify.sh + notify.env (bot y chat). Lo usan backup.sh (fallas y checks de integridad), scripts/linkedin-reminder.sh y el hub (tgAlert, vía env_file). Hoy apunta al bot personal @bot-de-avisos; cambiar de bot es editar notify.env.

Resultados
  • 16 servicios corriendo en contenedores sobre un único servidor de 8 GB de RAM, separados en tres redes aisladas.
  • Acceso a todos los paneles internos con un único login de dos factores (Google + TOTP propio), sin bypass.
  • Una sola superficie pública, protegida por token; el resto solo es alcanzable por VPN.
  • Backups cifrados local + offsite con verificación de integridad; rediseñar el alcance llevó cada snapshot de 2-3 GB a unos 58 MB, y cubrió por primera vez todo el código y la historia de los proyectos.
  • Trazas de punta a punta (app, gateway, proveedor) con un collector propio.

Papers

Métodos escritos para que otros equipos los apliquen, con su evidencia y sus referencias.

Documento metodológico · v1.0 · octubre de 2026 · 19 páginas · ES

De Scrum a Spec-Driven Development

Un método para equipos que ya trabajan con Scrum: cómo aplicarlo, cómo reutilizar sus ceremonias y cómo medir la madurez de la adopción.

Cuando un agente de IA genera la mayor parte del código, el costo de construir cae en órdenes de magnitud, mientras que decidir qué construir y validar lo construido sigue dependiendo de personas. Scrum se diseñó sobre la estructura de costos inversa. El documento presenta Spec-Driven Development en términos operativos: el ciclo de trabajo con sus artefactos y gates, cómo se reconvierte cada ceremonia de Scrum, las métricas que reemplazan a story points y velocity, por qué no es un regreso a la cascada y un modelo de madurez de tres niveles (spec-first, spec-anchored y spec-as-source). Incluye un ejemplo completo en una app móvil, un plan de transición de ocho semanas y un catálogo de modos de falla.

spec-driven development · Scrum · agentes de IA · diseño por contrato · quality gates · modelo de madurez

Cómo citar

Roberts, J. (2026). De Scrum a Spec-Driven Development (versión 1.0).

© 2026 Jorge Roberts. Todos los derechos reservados. La autoría también está en los metadatos del PDF.

Posts

Lo que escribo sobre delivery con agentes. Se publican en LinkedIn y llegan acá solos. También por RSS.

Story points measure volume. Measure validation instead.

2026-11-19

Story points measure volume. Measure validation instead.

Texto completo

Most teams still plan sprints in story points. Once an AI agent writes most of the code, I think that number stops telling you much.

Generating code got cheap. Checking that it's right didn't.

For 15 years I ran delivery where velocity was a decent proxy. Building was the slow, expensive part, so counting what got built made sense.

Now an agent can produce a feature in an afternoon. A team can double its points and, in the same sprint, pile up rework, drift between spec and code, and review debt that never shows up on the board.

So the question I ask a team has changed. How much of what you built was accepted the first time someone reviewed it?

Across the 70+ AI projects I've worked with this year, these are the numbers I look at, with the bar I set: - first-pass acceptance: 80% or more of agent output approved without rework - rework: under 20% of effort going back into work already marked done - validation latency: finished work waits less than 1 day for a person to check it

None of them reward volume. A team that generates faster than it can verify sees them slip within 2 or 3 sprints, long before velocity says anything is wrong.

When building is nearly free, judgement is the scarce resource. That's what the plan should measure.

If you run teams with agents in the loop: what replaced story points in your planning, if anything did?

#SoftwareDelivery #AIAgents #EngineeringManagement

Human review should follow risk, not volume.

2026-11-17

Human review should follow risk, not volume.

Texto completo

65% to 78%. That's the number Anthropic chose to report about how its team reviews AI-written code.

Not lines reviewed. Not velocity. The share of pull requests that pass after a single review round.

This week the Claude Code team explained how they review code now that agents write a growing share of it. From a delivery point of view, two decisions stood out to me.

First, human review follows risk, not volume. Low-risk changes can merge without human approval. Medium-risk changes need one person. High-risk changes need two, and sensitive areas like CI always get a human.

Second, review loops are capped. After three rounds, the author is asked to rethink the implementation instead of patching it again. PRs that needed five or more rounds dropped from 8.9% to 1.5%.

That second rule is the one I see missing most often. Endless review rounds are where AI speed quietly turns into rework, and nobody's board shows it.

The takeaway for delivery leaders: decide in advance where human judgement is required, and measure whether work passes the first time.

The person directing the agent is still accountable for the code. Governance just decides where that person's attention goes.

How does your team decide which AI-generated changes still need two human approvals?

#SoftwareDelivery #AIAgents #EngineeringManagement