# CAPA COGNITIVA - GRACE (Sistema de Modulos IA)
**Version:** 2.0
**Estado:** Enterprise Standard
**Filosofia Base:** Microservicios Cognitivos - Contrato Comun - Determinismo y Observabilidad

---

# 1. Introduccion a GRACE

GRACE no es un chatbot.
GRACE es un **conjunto de 18 microservicios cognitivos desacoplados**, especializados en tareas de:

- Vision
- Voz
- Biometria
- Semantica
- Extraccion de datos
- Normalizacion
- Clasificacion

GRACE representa la **capa de cognicion** del ecosistema.
No toma decisiones.
No altera estados.
No escribe en la Base de Datos.

**"GRACE transforma, Alfred decide."**

---

# 2. Integracion con S-CONTRACT

Toda llamada a GRACE debe seguir estrictamente el S-CONTRACT v2.0.

## 2.1 Request (Perfil LITE)

```json
{
  "contract_version": "2.0",
  "profile": "LITE",
  "envelope": {
    "trace_id": "uuid-v4-global",
    "idempotency_key": "sha256-del-input"
  },
  "routing": {
    "module": "CLASSIFIER"
  },
  "context": {
    "lang": "es",
    "mode": "strict"
  },
  "payload": {
    "type": "text",
    "encoding": "utf-8",
    "content": "Texto a procesar"
  }
}
```

## 2.2 Response

```json
{
  "contract_version": "2.0",
  "profile": "LITE",
  "envelope": {
    "trace_id": "uuid-v4-global",
    "idempotency_key": "sha256-del-input",
    "timestamp_end": "2025-12-18T10:30:00.450Z"
  },
  "status": {
    "code": "SUCCESS",
    "fallback_level_used": 0,
    "provider_used": "groq"
  },
  "result": {
    "schema": "classifier_output_v1",
    "data": {
      "category": "FINANZAS",
      "confidence": 0.98
    }
  },
  "quality": {
    "confidence": 0.98,
    "coverage": 1.0,
    "tokens_input": 150,
    "tokens_output": 45
  },
  "metadata": {
    "model_id": "llama-3-70b-instruct",
    "processing_ms": 340
  },
  "errors": [],
  "warnings": []
}
```

### Status codes

| Codigo | Significado |
|--------|-------------|
| `SUCCESS` | Ejecucion completa y valida |
| `PARTIAL` | Resultado incompleto pero usable |
| `ERROR` | Fallo no recuperable |
| `TIMEOUT` | Excedio TTL |
| `FALLBACK` | Exito usando modulo alternativo |

---

# 3. Catalogo de Modulos (Los 18 Microservicios)

GRACE se divide en cinco familias.

---

## FAMILIA A - VISION (Procesado Documental)

### **1. IMG_PREPROCESS**
Normalizacion de entrada.
Operaciones:
- Crop inteligente
- Denoise
- Upscale 2x
- Grayscale

### **2. PDF_SCANNER**
Limpieza avanzada para documentos escaneados.
Operaciones:
- Deskew
- Binarizacion adaptativa
- Eliminacion bordes negros

### **3. OCR_CORE**
Extraccion de texto.
Incluye:
- Layout analysis
- HOCR
- Texto plano

---

## FAMILIA B - VOZ (Reuniones)

### **4. ASR_ENGINE**
Reconocimiento del habla.
- Modelo: Whisper Large v3 / Faster Whisper
- Diarizacion A/B
- Timestamps por frase

### **5. TTS_ENGINE**
Sintesis de voz neutral para notificaciones internas.

---

## FAMILIA C - IDENTIDAD (Biometria)

### **6. FACE_VECTOR**
Vector biometrico facial (Float32 L2).
No guarda fotos, solo matematicas.

### **7. ID_CONSOLIDATION**
Fusion de identidades de un mismo Player.
Algoritmo: **Mediana geometrica** para eliminar outliers.

### **8. AVATAR_GEN**
Generacion de avatar neutral 512x512 a partir del vector consolidado.

---

## FAMILIA D - SEMANTICA (NLP)

### **9. EMBEDDINGS**
Vectorizacion semantica para busquedas.

### **10. SUMMARIZER**
Resumen estructurado:
```json
{
  "objetivos": [],
  "acuerdos": [],
  "riesgos": []
}
```

### **11. TASK_EXTRACTOR**
Mineria de acciones, responsabilidades y fechas.

### **12. CLASSIFIER**
Asigna SET_HST basado en contenido textual.

### **13. SIMILARITY**
Comparador vectorial (Cosine Similarity).

---

## FAMILIA E - UTILIDADES

### **14. FIELD_EXTRACTOR**
Lectura estructurada mediante regex + IA.
Ej.: CIF, fechas, importes.

### **15. HASHER**
Generador oficial de SHA256 y UUID v4.

### **16. INPUT_NORMALIZER**
Traduccion de formatos y enumeraciones.

### **17. OUTPUT_ADAPTER**
Adaptacion a formatos legacy.

### **18. LANG_DETECT**
Identificacion ISO 639-1.

---

# 4. Cadenas de Fallback (Resiliencia Operativa)

GRACE nunca falla silenciosamente.
Cada modulo define una cadena de degradacion via `fallback_chain`.

## Ejemplo OCR

```json
"routing": {
  "module": "OCR_CORE",
  "fallback_chain": ["OCR_LOCAL", "OCR_GROQ", "OCR_OPENAI"]
}
```

## Ejemplo ASR

```json
"routing": {
  "module": "ASR_ENGINE",
  "fallback_chain": ["ASR_WHISPER_LOCAL", "ASR_FASTER_WHISPER", "ASR_GROQ"]
}
```

---

# 5. Filosofia Operativa de GRACE

### Stateless
GRACE nunca guarda estado.

### Determinista
La misma entrada -> siempre la misma salida.

### Intercambiable
Se puede sustituir un modelo por otro sin romper el sistema.

### Trazable
Toda ejecucion queda registrada via trace_id.

### No persiste datos sensibles
Los archivos viven solo en almacenamiento gestionado.

---

# 6. Relacion GRACE <-> Alfred <-> SFE

### GRACE transforma
OCR, ASR, vectores, embeddings.

### Alfred decide
Valida, encamina, escribe en SFE.

### SFE registra
El estado final y su evidencia.

```
Entrada (URL)
    |
GRACE (microservicio)
    |
Transformacion estructurada
    |
Alfred (validacion)
    |
SFE (narrativa oficial)
```

---

# 7. M-CONTRACTs

Cada modulo debe definir su M-CONTRACT extendiendo S-CONTRACT.

Ver carpeta `/m-contracts/` para definiciones formales de:
- CLASSIFIER.json
- OCR_CORE.json
- ASR_ENGINE.json
- (18 modulos total)

---

**Fin del Documento MODULOS_IA - Version 2.0**

*Sistema GRACE - "GRACE transforma, Alfred decide"*