# Guia Para IA: Generar Flujos JSON V1

Esta guia esta escrita para que otra IA genere flujos JSON V1 de Medusa de forma consistente y sin inventar estructura.

Si la tarea incluye tambien reconstruir prompts modulares desde un prompt legacy:
- ver [GUIA_PARA_IA_GENERAR_PAQUETE_MODULAR.md](/c:/Apache24/htdocs/sidelink/backend/IA/GUIA_PARA_IA_GENERAR_PAQUETE_MODULAR.md)

Usala cuando se le quiera pedir a otra IA que arme un flujo a partir de contexto funcional.

## Rol esperado de la IA

Tu tarea es generar JSONs de flujos V1 para Medusa.

No debes:
- inventar campos fuera del standard
- mezclar formato legacy con V1
- responder con explicaciones largas si el usuario pidio solo el JSON
- inventar tools no soportadas
- inventar tipos de paso no soportados

Debes:
- producir JSON valido
- respetar exactamente el standard V1
- elegir nombres claros y consistentes
- modelar el flujo de forma deterministica
- usar `branch` cuando la decision depende de un valor
- usar `action` cuando hay tool backend

## Standard exacto permitido

El flujo debe tener esta forma general:

```json
{
  "id": "flujo_xxx_v1",
  "version": 1,
  "nombre": "Nombre visible",
  "intent_principal": "prompt_xxx",
  "settings": {
    "entry_step": "id_del_primer_step"
  },
  "tool_permissions": {},
  "slots": {},
  "backend_facts": {},
  "steps": []
}
```

## Campos de raiz permitidos

Solo usar:
- `id`
- `version`
- `nombre`
- `intent_principal`
- `settings`
- `tool_permissions`
- `slots`
- `backend_facts`
- `steps`

No usar:
- `descripcion`
- `pasos`
- `solo_si`
- `cuando`
- `faltan`
- `accion`
- `tipo`

Esos pertenecen al formato legacy, no a V1.

## Values validos

### Tipos de step permitidos

Solo usar:
- `question`
- `message`
- `action`
- `branch`
- `end`

### Actions permitidas

Solo usar:
- `buscar_cliente`
- `transferir_operador`
- `registrar_compromiso_pago`

### Tipos de slot y backend_fact permitidos

Solo usar:
- `text`
- `enum`
- `boolean`

### Operadores permitidos en branch

Solo usar:
- `equals`
- `not_equals`
- `exists`

### Origenes permitidos en branch

Solo usar:
- `slot`
- `fact`

## Semantica obligatoria por tipo de step

### `question`

Sirve para pedir o confirmar un dato.

Debe tener:
- `id`
- `type`
- `slot`
- `message`

Puede tener:
- `next_step`

Ejemplo:

```json
{
  "id": "pedir_dni",
  "type": "question",
  "slot": "dni_cuit",
  "message": "Pedir DNI o CUIT para validar la cuenta.",
  "next_step": "validar_cliente"
}
```

### `message`

Sirve para informar algo y continuar.

Debe tener:
- `id`
- `type`
- `message`

Puede tener:
- `next_step`

Ejemplo:

```json
{
  "id": "cliente_no_encontrado",
  "type": "message",
  "message": "Pedir otro DNI o CUIT porque no se pudo validar la cuenta.",
  "next_step": "pedir_dni"
}
```

### `action`

Sirve para ejecutar una tool backend.

Debe tener:
- `id`
- `type`
- `action`

Puede tener:
- `requires`
- `params`
- `on_success`
- `on_failure`

Ejemplo:

```json
{
  "id": "validar_cliente",
  "type": "action",
  "action": "buscar_cliente",
  "requires": ["dni_cuit"],
  "on_success": "evaluar_estado_admin",
  "on_failure": "cliente_no_encontrado"
}
```

### `branch`

Sirve para decidir a que paso ir.

Debe tener:
- `id`
- `type`
- `branches`

Puede tener:
- `default_next`

Ejemplo:

```json
{
  "id": "evaluar_estado_admin",
  "type": "branch",
  "branches": [
    {
      "when": {
        "fact": "estado_administrativo",
        "equals": "activo"
      },
      "go_to": "pedir_tipo_problema"
    }
  ],
  "default_next": "pedir_tipo_problema"
}
```

### `end`

Sirve para terminar el flujo.

Formato:

```json
{
  "id": "fin",
  "type": "end"
}
```

## Reglas para `slots`

Los `slots` representan datos conversacionales.

Cada slot puede tener:
- `type`
- `required`
- `label`
- `description`
- `values`

Ejemplo:

```json
{
  "tipo_problema": {
    "type": "enum",
    "required": true,
    "label": "Tipo de problema",
    "description": "Tipo de inconveniente tecnico",
    "values": ["sin_servicio", "lentitud_cortes", "otro"]
  }
}
```

Reglas:
- `label` debe ser humano y corto
- `description` debe explicar el sentido del dato
- `values` solo para `enum`
- no inventar `min`, `max`, `regex`, `placeholder`, etc.

## Reglas para `backend_facts`

Los `backend_facts` representan hechos confirmados por backend.

Ejemplo:

```json
{
  "estado_administrativo": {
    "type": "enum",
    "label": "Estado administrativo",
    "description": "Estado del servicio informado por backend",
    "values": ["activo", "cortado_falta_pago", "suspendido", "desconocido"]
  }
}
```

Importante:
- aunque hoy algunos facts no esten implementados en todos los providers, igual deben declararse si el flujo depende de ellos
- no mezclar `backend_facts` con `slots`

## Reglas de modelado

### 1. Separar datos conversacionales de datos backend

Usar `slots` para:
- DNI dicho por el cliente
- localidad
- nombre
- tipo de problema

Usar `backend_facts` para:
- cliente verificado
- estado administrativo
- conexion estado

### 2. No usar `branch` para pedir datos

`branch` solo decide.

No debe hacer preguntas.

### 3. No usar `message` como texto final de WhatsApp

`message` es una instruccion interna para GPT.

Debe escribirse como intencion funcional.

Correcto:
- `"message": "Pedir otro DNI porque no se pudo validar la cuenta."`

Incorrecto:
- `"message": "Hola, no pude validar tu cuenta, por favor..."` como copy definitivo

### 4. Toda derivacion debe ser un `action`

Si el flujo deriva a un operador, debe usar:

```json
{
  "type": "action",
  "action": "transferir_operador",
  "params": {
    "area": "ventas",
    "motivo": "Lead de ventas completo"
  }
}
```

### 5. Todo flujo debe terminar en `end`

Siempre agregar un paso final:

```json
{
  "id": "fin",
  "type": "end"
}
```

## Convenciones recomendadas de nombres

### IDs de step

Usar verbos claros:
- `pedir_dni`
- `validar_cliente`
- `evaluar_estado_admin`
- `derivar_cobranza`
- `fin`

Evitar:
- `step1`
- `paso_1`
- `rama_a`

### Slots

Usar snake_case y nombres de dato:
- `dni_cuit`
- `nombre_apellido`
- `tipo_problema`
- `resultado_final`

Evitar:
- `respuesta`
- `dato1`
- `pregunta_cliente`

### Backend facts

Usar nombres de estado:
- `cliente_verificado`
- `dni_validado`
- `estado_administrativo`

## Plantilla minima para generar un flujo

Usar esta base:

```json
{
  "id": "flujo_xxx_v1",
  "version": 1,
  "nombre": "Nombre del flujo",
  "intent_principal": "prompt_xxx",
  "settings": {
    "entry_step": "primer_step"
  },
  "tool_permissions": {},
  "slots": {},
  "backend_facts": {},
  "steps": []
}
```

## Ejemplo completo de soporte

```json
{
  "id": "flujo_soporte_v1",
  "version": 1,
  "nombre": "Soporte tecnico",
  "intent_principal": "prompt_soporte",
  "settings": {
    "entry_step": "pedir_dni"
  },
  "tool_permissions": {
    "buscar_cliente": true,
    "transferir_operador": true
  },
  "slots": {
    "dni_cuit": {
      "type": "text",
      "required": true,
      "label": "DNI o CUIT",
      "description": "Documento informado por el cliente"
    },
    "tipo_problema": {
      "type": "enum",
      "required": true,
      "label": "Tipo de problema",
      "description": "Tipo de inconveniente tecnico",
      "values": ["sin_servicio", "lentitud_cortes", "otro"]
    }
  },
  "backend_facts": {
    "estado_administrativo": {
      "type": "enum",
      "label": "Estado administrativo",
      "description": "Estado del servicio segun backend",
      "values": ["activo", "cortado_falta_pago", "suspendido", "desconocido"]
    }
  },
  "steps": [
    {
      "id": "pedir_dni",
      "type": "question",
      "slot": "dni_cuit",
      "message": "Pedir DNI o CUIT para verificar la cuenta.",
      "next_step": "validar_cliente"
    },
    {
      "id": "validar_cliente",
      "type": "action",
      "action": "buscar_cliente",
      "requires": ["dni_cuit"],
      "on_success": "evaluar_estado_admin",
      "on_failure": "cliente_no_encontrado"
    },
    {
      "id": "cliente_no_encontrado",
      "type": "message",
      "message": "Pedir otro DNI o CUIT porque no se pudo validar la cuenta.",
      "next_step": "pedir_dni"
    },
    {
      "id": "evaluar_estado_admin",
      "type": "branch",
      "branches": [
        {
          "when": {
            "fact": "estado_administrativo",
            "equals": "activo"
          },
          "go_to": "pedir_tipo_problema"
        }
      ],
      "default_next": "pedir_tipo_problema"
    },
    {
      "id": "pedir_tipo_problema",
      "type": "question",
      "slot": "tipo_problema",
      "message": "Preguntar si el problema es sin servicio, lentitud o cortes, u otro inconveniente tecnico.",
      "next_step": "fin"
    },
    {
      "id": "fin",
      "type": "end"
    }
  ]
}
```

## Prompt recomendado para pedirle a otra IA que genere un flujo

Podes usar literalmente esto:

```txt
Quiero que generes un flujo JSON en Medusa Flow Standard V1.

Reglas obligatorias:
- Devolvé SOLO JSON válido.
- No agregues explicaciones.
- No inventes campos fuera de este estándar:
  id, version, nombre, intent_principal, settings, tool_permissions, slots, backend_facts, steps.
- version debe ser 1.
- Los steps solo pueden usar type: question, message, action, branch, end.
- Las actions solo pueden ser: buscar_cliente, transferir_operador, registrar_compromiso_pago.
- En branch, cada rama debe usar when con slot o fact, y un operador equals, not_equals o exists.
- Todo flujo debe terminar en un step type=end con id=fin.
- message es una instrucción interna para GPT, no el texto final de WhatsApp.

Contexto funcional del flujo:
[PEGAR ACA EL CONTEXTO]
```

## Checklist final para la IA

Antes de responder, verificar:
- JSON valido
- `version = 1`
- `entry_step` existe
- todos los `step.id` son unicos
- todos los targets existen
- los `slots` usados en `question` existen
- los `backend_facts` usados en `branch` existen
- hay un `end`
- no hay campos legacy