Archive: System v4 - Estado al 2024-12-24
This commit is contained in:
ARCHITECT
298
v4-archive/contratos-comunes/docs/MODULOS_IA.md
Normal file
298
v4-archive/contratos-comunes/docs/MODULOS_IA.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# 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"*
|
||||
Reference in New Issue
Block a user