Archive: System v4 - Estado al 2024-12-24

v4-archive/grace/docs/README_MODULES.md

@@ -0,0 +1,139 @@
+# ✨ GRACE
+
+**Capa Cognitiva Determinista - Sistema SFE/HST Enterprise v5.0**
+
+> "GRACE transforma, Alfred decide."
+
+---
+
+## ¿Qué es GRACE?
+
+GRACE es la capa cognitiva del sistema: 18 microservicios de IA desacoplados.
+
+- NO es chatbot
+- NO guarda estado
+- NO toma decisiones de flujo
+- Transforma datos según request
+- Intercambiable: sustituir modelo sin romper sistema
+
+```
+                    ┌──────────────────┐
+                    │   ALFRED (n8n)   │
+                    │   Orquestador    │
+                    └────────┬─────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+              ▼              ▼              ▼
+       ┌──────────┐   ┌──────────┐   ┌──────────┐
+       │  LOCAL   │   │  LOCAL   │   │  REMOTO  │
+       │  Ligero  │   │  Medio   │   │  Pesado  │
+       │ (CPU)    │   │ (CPU+)   │   │ (GPU)    │
+       └──────────┘   └──────────┘   └──────────┘
+       
+       Whisper-tiny   Embeddings     GPT-4o Vision
+       Regex/Rules    OCR-Local      Claude Sonnet
+       Hashing                       Whisper Large
+```
+
+---
+
+## Los 18 Módulos
+
+### Familia VISIÓN
+| Módulo | Función |
+|--------|---------|
+| `IMAGE_PROCESSOR` | Limpieza, resize, crop, denoise |
+| `PDF_SCANNER` | Recorte automático, deskew, contraste |
+| `OCR_CORE` | Lectura de texto |
+
+### Familia VOZ
+| Módulo | Función |
+|--------|---------|
+| `ASR` | Audio → Texto |
+| `TTS` | Texto → Audio |
+
+### Familia IDENTIDAD
+| Módulo | Función | PII |
+|--------|---------|-----|
+| `FACE_VECTOR` | Extrae vector facial 512D | ✓ |
+| `ID_CONSOLIDATION` | Fusiona múltiples vectores | ✓ |
+| `AVATAR_GEN` | Genera avatar desde vector | - |
+
+### Familia NLP
+| Módulo | Función |
+|--------|---------|
+| `SUMMARIZER` | Resume texto |
+| `CLASSIFIER` | Clasifica documentos |
+| `TASK_DETECTOR` | Extrae tareas de texto |
+
+### Familia SEMÁNTICA
+| Módulo | Función |
+|--------|---------|
+| `EMBEDDINGS` | Texto → vectores |
+| `SIMILARITY` | Compara vectores |
+
+### Familia ESTRUCTURA
+| Módulo | Función |
+|--------|---------|
+| `FIELD_EXTRACTOR` | Extrae campos de documentos |
+| `HASH_SIGNER` | SHA256/512/BLAKE2B |
+| `LANG_NORMALIZER` | Detecta idioma |
+| `INPUT_TRANSLATOR` | Normaliza entrada |
+| `OUTPUT_TRANSLATOR` | Formato legacy |
+
+---
+
+## Arquitectura Híbrida
+
+| Tier | Tipo | Proveedores |
+|------|------|-------------|
+| **TIER 1** | GPU Serverless | RunPod, Modal, Replicate |
+| **TIER 2** | APIs Premium | OpenAI, Anthropic, Google |
+
+**Routing por módulo**: Cada módulo define su cadena de fallback.
+
+---
+
+## Inicio Rápido
+
+```bash
+# Instalar
+pip install -r requirements.txt
+
+# Configurar
+cp .env.example .env
+
+# Ejecutar
+uvicorn app.main:app --reload
+
+# Verificar
+curl http://localhost:8000/health
+```
+
+---
+
+## Contrato Común v1.2
+
+Todos los módulos usan la misma interfaz:
+
+```json
+{
+  "envelope": {
+    "trace_id": "uuid",
+    "step_id": "uuid"
+  },
+  "routing": {
+    "module": "OCR_CORE",
+    "version": "1.0"
+  },
+  "payload": {
+    "type": "image",
+    "content": "base64..."
+  }
+}
+```
+
+---
+
+**Sistema SFE/HST Enterprise v5.0**