299 lines
5.3 KiB
Markdown
299 lines
5.3 KiB
Markdown
# 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"*
|