system-docs/02_COMPONENTES/servicios externos/gestoria.md

Gestoría

Nombre: Grace
Versión: 2.0
Estado: Enterprise Standard

---

Descripción

GRACE no es un chatbot. Es un conjunto de 18 microservicios cognitivos desacoplados.

┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPIO GRACE                              │
│                                                                 │
│       "GRACE transforma, Producción (Alfred/Jared) decide"     │
└─────────────────────────────────────────────────────────────────┘

---

Características

Propiedad	Valor
Stateless	No guarda estado
Determinista	Misma entrada → misma salida
Intercambiable	Modelos sustituibles
Trazable	Todo via trace_id

GRACE no:

• Toma decisiones
• Altera estados
• Escribe en base de datos

---

Infraestructura

Aspecto	Valor
Plataforma	RunPod Serverless
GPU	NVIDIA L4 (24GB)
Endpoint	https://api.runpod.ai/v2/{id}
Modos	runsync, run, status

---

Catálogo de 18 Módulos

FAMILIA A - VISIÓN (Procesado Documental)

#	Módulo	Función
1	IMG_PREPROCESS	Normalización: crop, denoise, upscale, grayscale
2	PDF_SCANNER	Limpieza escaneados: deskew, binarización, bordes
3	OCR_CORE	Extracción texto: layout analysis, HOCR

FAMILIA B - VOZ (Reuniones)

#	Módulo	Función
4	ASR_ENGINE	Reconocimiento habla: Whisper Large v3, diarización
5	TTS_ENGINE	Síntesis voz neutral para notificaciones

FAMILIA C - IDENTIDAD (Biometría)

#	Módulo	Función
6	FACE_VECTOR	Vector biométrico facial (Float32 L2)
7	ID_CONSOLIDATION	Fusión identidades: mediana geométrica
8	AVATAR_GEN	Avatar neutral 512x512 desde vector

FAMILIA D - SEMÁNTICA (NLP)

#	Módulo	Función
9	EMBEDDINGS	Vectorización semántica para búsquedas
10	SUMMARIZER	Resumen estructurado: objetivos, acuerdos, riesgos
11	TASK_EXTRACTOR	Minería de acciones, responsables, fechas
12	CLASSIFIER	Asigna tags HST basado en contenido
13	SIMILARITY	Comparador vectorial (Cosine Similarity)

FAMILIA E - UTILIDADES

#	Módulo	Función
14	FIELD_EXTRACTOR	Lectura estructurada: CIF, fechas, importes
15	HASHER	Generador SHA256 y UUID v4
16	INPUT_NORMALIZER	Traducción formatos y enumeraciones
17	OUTPUT_ADAPTER	Adaptación a formatos legacy
18	LANG_DETECT	Identificación idioma ISO 639-1

---

Cadenas de Fallback

Cada módulo define degradación vía fallback_chain en S-CONTRACT:

Ejemplo OCR

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

Ejemplo ASR

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

---

Integración con S-CONTRACT

Todos los módulos GRACE cumplen S-CONTRACT sin excepciones. No hay contratos específicos por módulo.

Request (LITE)

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

Response

{
  "contract_version": "2.1",
  "profile": "LITE",
  "status": {
    "code": "SUCCESS",
    "provider_used": "groq"
  },
  "result": {
    "data": {
      "category": "FINANZAS",
      "confidence": 0.98
    }
  },
  "quality": {
    "confidence": 0.98,
    "tokens_input": 150,
    "tokens_output": 45
  },
  "metadata": {
    "model_id": "llama-3.1-70b-versatile",
    "processing_ms": 340
  }
}

---

Relación con Otros Componentes

GRACE es un servicio de transformación. Cuando termina de procesar, envía el resultado a Secretaría (Clara/Margaret) como cualquier otro origen:

┌─────────────────────────────────────────────────────────────────┐
│                     PUNTO DE ENTRADA ÚNICO                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   GRACE ──────┐                                                │
│   Penny ──────┼──► Secretaría (Clara/Margaret)                 │
│   Packet ─────┤                                                │
│   Manual ─────┘                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

GRACE no es un paso del flujo de datos. Es un servicio que cualquier componente puede invocar vía S-CONTRACT para obtener transformaciones cognitivas (OCR, transcripción, clasificación, etc.).

---

Compatibilidad Universal

El sistema está diseñado para que cuando aparezcan módulos mejores, encajen sin trabajo añadido. S-CONTRACT es el marco de compatibilidad universal — cualquier módulo que lo cumpla es interoperable.