# ✨ 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**