## Asset Header

- **Asset ID:** TP-MPX-AI-SherpaOS-Alex-Implementacion-v01
- **Version:** v01
- **Status:** Draft
- **Owner:** Victor Heredia
- **IntellBank:** IB-MPX-MasterPlaybooks
- **Tipo:** TP — Transfer Packet
- **Propósito:** Transfer Pack Técnico — Alex / Implementación AI Sherpa OS
- **Última actualización:** 2026-04-11

---

# Transfer Pack Técnico — Alex / Implementación AI Sherpa OS
## AI-SherpaOS-TP-Alex-Implementacion-v01

---

## Header

- **Para:** Alex (Tech Lead / Backend)
- **De:** Victor Heredia + Sherpa IA (sesión de arquitectura 2026-03-25)
- **Versión:** v1.0
- **Propósito:** Activar la implementación de Modo 2 (Tu Sherpa IA como servicio) y Modo 3 (AI Sherpa OS para MasterPlaybooks) con todo el contexto técnico ya tomado de decisiones. Sin necesidad de re-leer la conversación.
- **Documentos de referencia** (leer antes de escribir código):
  1. `ai_sherpa_os_canonical_v0.1.md` — arquitectura completa del sistema
  2. `ai_sherpa_os_data_model_event_ledger_v0.1.md` — schema SQL, Edge Functions, API endpoints, MCP tools
  3. Este documento (TP de implementación)

---

## Contexto de la sesión — lo que se decidió

Esta sesión resolvió la duda central de Alex: **¿cómo entra el Event Ledger en la infraestructura existente de MasterPlaybooks?**

**La respuesta:** No reemplaza nada. Se suma como segunda fuente de contexto. El chatbot existente hace 3 llamadas adicionales por ciclo de conversación.

También se clarificó la arquitectura de los 3 modos. Están documentados abajo.

---

## Los 3 Modos — Arquitectura Definitiva

### Modo 1 — BrainOS Personal de Victor (YA CORRE, NO TOCAR)

```
Claude Desktop de Victor
    ↓ MCP (protocolo local)
Supabase de Victor (instancia dedicada, ya provisionada)
    tabla: thoughts
    ↓
OpenRouter → text-embedding-3-small → pgvector search

Estado: PRODUCCIÓN. 109+ thoughts. Victor opera esto hoy.
Acción de Alex: ninguna. No tocar.
```

---

### Modo 2 — Tu Sherpa IA / SherpaX como Servicio para Clientes

**Fase actual (Track A — dedicado por cliente):**

```
Cliente CEO → Claude Desktop con URL personalizada
    ↓ MCP → Supabase del cliente (instancia dedicada)
    tabla: thoughts / memories
    ↓
OpenRouter → embeddings → búsqueda semántica

Provisioning: SysOps de EmpowerLabs crea instancia Supabase
              por cliente (~15-20 min)
Costo: Supabase Free por cliente hasta que escale
```

**Fase futura (Multi-tenant hosted — Q3 2026):**

```
Cliente CEO → Claude Desktop con URL de EmpowerLabs
    ↓ HTTPS
[MCP Server Propio de EmpowerLabs] ← ESTO HAY QUE CONSTRUIR
    ↓ autentica JWT / API key del cliente
    ↓ enruta al user_id correcto
Supabase EmpowerLabs (una instancia, todos los clientes)
    tabla: thoughts WHERE user_id = cliente_X (RLS)
    ↓
OpenRouter → embeddings
```

**Para los primeros 10-20 clientes: Track A (dedicado).** No construir el MCP Server multi-tenant todavía — es Q3 2026.

---

### Modo 3 — AI Sherpa OS para MasterPlaybooks

```
Usuario web de MasterPlaybooks
    ↓ HTTP request al chatbot
[Servidor MP existente — Node/Python]
    ↓ consulta MySQL: vectores del contenido del Playbook
    ↓ consulta Supabase AI Sherpa OS: estado + memorias del usuario (NUEVO)
    ↓ construye prompt enriquecido
    ↓ llama OpenRouter (o OpenAI directo — puede quedarse igual)
    ↓ respuesta al usuario
    ↓ POST /events al Event Ledger (NUEVO)

Supabase AI Sherpa OS (instancia nueva o separada)
    tablas: events, state, memories, sessions, users, artifacts
```

**Este es el trabajo de la Fase 1 del spec.**

---

## Decisiones de Infraestructura Tomadas

| Decisión | Respuesta |
|----------|-----------|
| ¿Supabase para todo? | Sí. Una instancia para AI Sherpa OS (MP). Instancias dedicadas para clientes Track A. |
| ¿Una o dos instancias Supabase? | Separadas hoy. Unificables después con RLS. Una instancia para MP, otra por cliente Sherpa IA. |
| ¿OpenRouter o OpenAI directo para MP? | OpenRouter recomendado (multi-modelo, no lock-in). El chatbot existente puede quedarse con OpenAI si el cambio es fricción — no es blocker para Fase 1. |
| ¿MySQL se elimina? | No. MySQL sigue como fuente del contenido vectorizado del Playbook. Supabase se suma para estado del usuario. |
| ¿El chatbot se reescribe? | No. Se modifican 3 puntos: lectura de estado, búsqueda de memorias, captura de eventos. |
| ¿Plan Supabase? | Free para desarrollo. Pro ($25/mes) desde primer cliente en producción. |
| ¿OpenRouter pricing? | Consumo bajo demanda. Embeddings: ~$0.02/millón tokens. LLM: según modelo. |
| ¿MCP Server propio cuándo? | Q3 2026 para multi-tenant. No es blocker para lanzamiento. |

---

## BLOQUE CRÍTICO — Lo que Alex necesita documentar antes de implementar el Modo 3

**Antes de tocar código, Alex necesita responder estas preguntas sobre la arquitectura actual de MasterPlaybooks.** Sin esta información, la integración puede tomar días en lugar de horas.

```
CUESTIONARIO DE ARQUITECTURA MASTERPLAYBOOKS
─────────────────────────────────────────────
Llenar por Alex antes de comenzar implementación del Modo 3

1. LENGUAJE Y FRAMEWORK DEL SERVIDOR
   ¿En qué está escrito el backend del chatbot? (Node.js, Python, PHP, otro)
   ¿Qué framework? (Express, FastAPI, Laravel, otro)
   Respuesta: _______________

2. CÓMO SE VECTORIZA EL PLAYBOOK
   ¿Cuándo se vectoriza el MD? ¿Al subir el archivo? ¿On-demand?
   ¿Qué modelo de embeddings usa? (text-embedding-ada-002, otro)
   ¿Las dimensiones del vector en MySQL? (1536, 768, otro)
   ¿Hay una función que recibe el mensaje del usuario y devuelve
    los chunks más relevantes del MD? ¿Cómo se llama?
   Respuesta: _______________

3. FLUJO DEL CHATBOT (paso a paso actual)
   Describir exactamente qué hace el servidor desde que recibe
   el mensaje del usuario hasta que devuelve la respuesta.
   Ejemplo:
     a) recibe POST /chat con { user_id, message, playbook_id }
     b) busca en MySQL los vectores más cercanos al mensaje
     c) construye prompt con [system] + [chunks del playbook] + [historial]
     d) llama POST https://api.openai.com/v1/chat/completions
     e) devuelve respuesta
   Respuesta (describir flujo real): _______________

4. IDENTIFICACIÓN DEL USUARIO
   ¿Cómo se identifica al usuario? ¿Hay un user_id? ¿Es el mismo
    en todas las sesiones? ¿Es un UUID, un email, un número?
   Respuesta: _______________

5. HISTORIAL DE CONVERSACIÓN
   ¿Se guarda el historial de mensajes en algún lado hoy?
   ¿MySQL? ¿Redis? ¿Solo en memoria de sesión?
   ¿Cuántos mensajes anteriores se pasan al LLM como contexto?
   Respuesta: _______________

6. IDENTIFICACIÓN DEL PLAYBOOK ACTIVO
   ¿Cómo sabe el servidor qué Playbook está usando el usuario?
   ¿Hay un playbook_id en el request? ¿En la sesión?
   ¿Qué Sherpas/Playbooks existen hoy en producción?
   Respuesta: _______________

7. DÓNDE VIVE EL SERVIDOR
   ¿Dónde está deployado? (VPS, AWS, Railway, Heroku, otro)
   ¿Tiene CI/CD? ¿O deploy manual?
   Respuesta: _______________

8. ACCESO A LA BASE DE DATOS
   ¿Alex tiene acceso directo al MySQL para agregar tablas/modificar?
   ¿O necesita coordinación con alguien?
   Respuesta: _______________
```

---

## Plan de Implementación — Modo 3 (AI Sherpa OS para MP)

*Basado en el spec completo de `ai_sherpa_os_data_model_event_ledger_v0.1.md`*

### PRE-REQUISITO: Llenar el cuestionario de arquitectura de arriba.

### Día 1 — Supabase Setup
```
1. Crear proyecto Supabase: "empowerlabs-sherpa-os"
   → Región: us-east-1 (o la más cercana a donde vive el servidor MP)

2. SQL Editor → ejecutar:
   create extension if not exists vector;

3. Settings → Edge Functions → Secrets → agregar:
   OPENROUTER_API_KEY = [obtener en openrouter.ai]
   EMBEDDING_MODEL = openai/text-embedding-3-small

4. Ejecutar schema completo (copiar de data_model_event_ledger_v0.1.md):
   - Función update_updated_at_column()
   - Tabla: users
   - Tabla: sessions
   - Tabla: events (con índice ivfflat)
   - Tabla: state
   - Tabla: memories (con índice ivfflat)
   - Tabla: artifacts

5. Verificar RLS en todas las tablas
   → Test: crear usuario de prueba, verificar que no puede
     ver datos de otro usuario

DoD: GET /health → 200 OK. Schema sin errores.
```

### Día 2 — Event Capture funcional
```
1. Deployar Edge Function: on-event-created
   (código en sección 4.1 del data_model doc)
   → genera embedding automáticamente al insertar evento
   → recalcula state

2. Implementar POST /events endpoint
   → puede ser una Edge Function o un endpoint en el servidor MP
   → persiste el evento + trigger la Edge Function

3. Implementar GET /state/{user_id}
   → devuelve estado actual calculado

4. Test end-to-end:
   curl -X POST /events -d '{
     "user_id": "test-uuid",
     "session_id": "test-session",
     "event_type": "user_message_submitted",
     "event_category": "interaction",
     "payload": { "message": "Quiero implementar NOM-035" }
   }'
   → verificar embedding generado en la fila
   → verificar GET /state devuelve estado actualizado

DoD: POST /events persiste + genera embedding. GET /state funciona.
```

### Día 3 — Memory Layer + Sessions
```
1. Deployar Edge Function: on-session-end
   → genera resumen de sesión via LLM
   → crea memoria episódica automáticamente

2. Implementar POST /session/start y POST /session/end

3. Implementar función SQL: search_memories
   (código en sección 4.3 del data_model doc)

4. Implementar POST /memories/search
   → búsqueda semántica

5. Test flujo completo:
   POST /session/start → session_id
   POST /events (varios: goal_declared, message, module_completed)
   POST /session/end → summary + memory_id generados
   POST /memories/search { query: "NOM-035" } → devuelve memoria

DoD: Flujo completo sesión → memoria episódica funcional.
```

### Día 4 — Integración con el Chatbot MP (el punto crítico)

**Este día depende de las respuestas del cuestionario de arquitectura.**

```
Modificaciones al chatbot existente:

ANTES de construir el prompt, agregar:
──────────────────────────────────────
// 1. Obtener estado del usuario
const state = await fetch(`${SUPABASE_URL}/functions/v1/get-state/${user_id}`)

// 2. Recuperar memorias relevantes
const memories = await fetch(`${SUPABASE_URL}/functions/v1/search-memories`, {
  method: 'POST',
  body: JSON.stringify({ user_id, query: userMessage, limit: 3 })
})

// 3. Construir prompt enriquecido
const prompt = buildPrompt({
  playbookChunks: mysqlResults,      // lo que ya existía
  userState: state.data,             // NUEVO: dónde está el usuario
  relevantMemories: memories.data,   // NUEVO: qué recordamos de él
  userMessage: message
})
──────────────────────────────────────

DESPUÉS de recibir respuesta del LLM, agregar:
──────────────────────────────────────
// Capturar el evento de la interacción
await fetch(`${SUPABASE_URL}/functions/v1/capture-event`, {
  method: 'POST',
  body: JSON.stringify({
    user_id,
    session_id,
    event_type: 'user_message_submitted',
    event_category: 'interaction',
    payload: { message: userMessage },
    playbook_id
  })
})
──────────────────────────────────────

PARA módulos completados (trigger desde el frontend o servidor):
──────────────────────────────────────
await fetch(`${SUPABASE_URL}/functions/v1/capture-event`, {
  body: JSON.stringify({
    event_type: 'module_completed',
    event_category: 'progress',
    payload: { module_id, score, completion_time_seconds }
  })
})
──────────────────────────────────────

DoD: Chatbot pasa contexto de Supabase al LLM. Eventos se capturan
     automáticamente en cada interacción.
```

### Día 5 — Demo interno + handoff a Juan Carlos
```
1. Flujo completo funcional con un Sherpa real (ej. Sherpa NOM-035)
2. Documentar 3 llamadas adicionales para Juan Carlos:
   - POST /session/start (cuándo llamarlo)
   - POST /events (qué eventos disparar desde el frontend)
   - GET /state/{user_id} (para mostrar progreso en UI)
3. Demo con Victor y equipo
4. Integración CRM: Juan Carlos toma el relay aquí

DoD: Demo funcional. Juan Carlos tiene spec para su integración.
```

---

## Plan de Implementación — Modo 2 (Tu Sherpa IA Track A)

*Este modo es más simple. Sigue el patrón BrainOS que ya existe.*

### Track A — Instancia dedicada por cliente (implementar ahora)

```
Por cada cliente nuevo:

1. Crear proyecto Supabase: "empowerlabs-client-[nombre]"
   → Free plan hasta que el cliente sea de pago

2. Ejecutar schema de BrainOS (igual al de Victor):
   - Extensión pgvector
   - Tabla: thoughts (igual a la de Victor)
   - Función: search_thoughts
   - RLS básico

3. Configurar MCP server de Supabase:
   → El cliente recibe una URL en formato:
     https://[project-ref].supabase.co/functions/v1/mcp
   → Agregar al claude_desktop_config.json del cliente:
   {
     "mcpServers": {
       "brainos": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-supabase"],
         "env": {
           "SUPABASE_URL": "https://[ref].supabase.co",
           "SUPABASE_ANON_KEY": "[anon-key]"
         }
       }
     }
   }

4. Enviar al cliente:
   - El bloque JSON de configuración
   - Instrucciones de 5 pasos para agregar al Claude Desktop

Tiempo total SysOps: ~15-20 minutos por cliente.
```

### Track B — MCP Server Propio de EmpowerLabs (multi-tenant, Q3 2026)

**No implementar todavía. Este es el diseño para cuando se necesite:**

```
ARQUITECTURA DEL MCP SERVER MULTI-TENANT
─────────────────────────────────────────

Stack sugerido: Node.js + Express (o Fastify)
Deploy: Railway o Fly.io (simple, sin Kubernetes)

Flujo:
Cliente → Claude Desktop
  URL: https://mcp.empowerlabs.com/mcp
  Header: Authorization: Bearer [api_key_del_cliente]
    ↓
[MCP Server EmpowerLabs]
  1. Valida el API key del cliente
  2. Resuelve el user_id asociado al key
  3. Ejecuta la herramienta MCP solicitada con ese user_id
  4. Devuelve resultado

Herramientas MCP a exponer:
  - capture_thought(content, tags)
  - search_thoughts(query, limit)
  - list_thoughts(limit)
  - thought_stats()

Tabla adicional en Supabase:
  CREATE TABLE api_keys (
    key_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    client_id uuid REFERENCES users(user_id),
    api_key text UNIQUE NOT NULL,
    created_at timestamptz DEFAULT now(),
    last_used_at timestamptz,
    active boolean DEFAULT true
  );

Autenticación:
  - Al provisionar un cliente: INSERT INTO api_keys + devolver key
  - En cada request MCP: validar key → obtener client_id → filtrar por RLS

Protocolo MCP sobre HTTP (SSE o streamable-http):
  El servidor implementa el protocolo MCP v1.0
  Referencia: https://modelcontextprotocol.io/docs/concepts/transports

Costo estimado de hosting: $5-10/mes en Railway para los primeros 50 clientes.

NO CONSTRUIR HASTA TENER 10+ CLIENTES ACTIVOS EN TRACK A.
```

---

## Variables de Entorno que Alex Necesita

```bash
# Supabase AI Sherpa OS (Modo 3 — MasterPlaybooks)
SUPABASE_URL_SHERPA_OS=https://[project-ref].supabase.co
SUPABASE_ANON_KEY_SHERPA_OS=[anon-key]
SUPABASE_SERVICE_ROLE_KEY_SHERPA_OS=[service-role-key]

# OpenRouter
OPENROUTER_API_KEY=sk-or-[...]
OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small
OPENROUTER_LLM_MODEL=anthropic/claude-3-haiku  # para metadata extraction
# Para respuestas del Sherpa, usar el modelo que ya usa MP hoy

# Supabase clientes Track A (una por cliente)
# Nombrar: SUPABASE_URL_CLIENT_[NOMBRE]
```

---

## Dependencias de npm para el servidor MP

```bash
# Cliente Supabase para el servidor Node/Python del chatbot
npm install @supabase/supabase-js

# Si el MCP Server propio se construye en Node (Q3 2026)
npm install @modelcontextprotocol/sdk express
```

---

## Catálogo mínimo de eventos para implementar en Fase 1

De todo el catálogo, Alex implementa solo estos 8 primero:

```
INTERACTION (para chatbot)
  user_message_submitted     → capturar mensaje del usuario
  sherpa_response_generated  → capturar respuesta del Sherpa
  session_started            → al iniciar sesión
  session_ended              → al cerrar sesión

PROGRESS (desde el frontend/servidor de MP)
  module_started             → usuario inicia módulo
  module_completed           → usuario completa módulo

SIGNAL (generados automáticamente por State Engine)
  blocker_detected           → cuando el LLM detecta bloqueo
  pricing_interest_detected  → cuando el usuario pregunta por precio
```

Los demás eventos del catálogo completo se implementan en iteraciones posteriores.

---

## Definition of Done — Fase 1 (esta semana)

```
Supabase AI Sherpa OS:
  ✅ Proyecto creado, pgvector habilitado
  ✅ Schema completo ejecutado sin errores
  ✅ RLS configurado y verificado
  ✅ Edge function on-event-created deployada
  ✅ POST /events funcional (persiste + genera embedding)
  ✅ GET /state/{user_id} funcional

Memory Layer:
  ✅ Tabla memories con embedding vector(1536)
  ✅ Edge function on-session-end deployada
  ✅ POST /session/start y POST /session/end funcionales
  ✅ Función SQL search_memories con cosine similarity
  ✅ POST /memories/search devuelve resultados relevantes

Integración MP:
  ✅ Chatbot hace 3 llamadas adicionales por ciclo
  ✅ Prompt enriquecido con state + memories del usuario
  ✅ Eventos capturados automáticamente en cada interacción
  ✅ Demo funcional con al menos un Sherpa (NOM-035 u otro)

Track A (Sherpa IA clientes):
  ✅ Proceso de provisioning documentado y probado end-to-end
  ✅ Un cliente de prueba (Victor o alguien del equipo) conectado y funcional
```

---

## Preguntas que Alex debe traer a la siguiente sesión con Victor

Después de leer los documentos canónicos y el cuestionario de arquitectura:

1. ¿El chatbot de MP usa streaming o respuesta completa? (afecta cómo se captura el evento de respuesta)
2. ¿Hay rate limits en OpenAI que puedan verse afectados por las llamadas adicionales de embeddings?
3. ¿La instancia de Supabase para MP puede estar en la misma región que el servidor de MP?
4. ¿Hay algún sistema de colas ya implementado? (útil para no bloquear la respuesta del chatbot al capturar eventos)
5. ¿Cuál es el Sherpa con más usuarios activos hoy? (ese es el candidato para la primera integración)

---

## Recursos

| Recurso | URL |
|---------|-----|
| Supabase Dashboard | https://supabase.com/dashboard |
| OpenRouter (API keys) | https://openrouter.ai/keys |
| MCP Protocol Docs | https://modelcontextprotocol.io |
| pgvector Docs | https://github.com/pgvector/pgvector |
| Supabase Edge Functions | https://supabase.com/docs/guides/functions |
| Spec completo (data model) | `ai_sherpa_os_data_model_event_ledger_v0.1.md` |
| Canonical doc (arquitectura) | `ai_sherpa_os_canonical_v0.1.md` |

---

*`AI-SherpaOS-TP-Alex-Implementacion-v01.md` v1.0 — EmpowerLabs — 2026-03-25*
*Preparado por: Victor Heredia + Sherpa IA*
*Actualizar con decisiones de arquitectura de Alex al inicio de implementación.*