Contratos Comunes - Sistema GRACE

Version: 2.1 Estado: Enterprise Standard

Especificacion del contrato comun (S-CONTRACT) y contratos de modulo (M-CONTRACT) para el ecosistema de microservicios cognitivos GRACE.

Arquitectura

Alfred (Orquestador n8n)
           |
           | S-CONTRACT v2.0
           v
+-------------------+
|       GRACE       |
|  18 Microservicios|
|     Cognitivos    |
+-------------------+
           |
           v
    SYS_LOG + SFE

Filosofia: "Alfred Decide, GRACE Transforma"

Estructura del Repositorio

contratos-comunes/
+-- README.md                    # Este archivo
+-- docs/
|   +-- S-CONTRACT.md            # Contrato comun del sistema (v2.1)
|   +-- MODULOS_IA.md            # Catalogo de 18 modulos
|   +-- ARQUITECTURA.md          # Vision arquitectonica
|   +-- SENTINEL.md              # Sistema de auditoria
|   +-- KEY_VAULT.md             # Gestion de llaves y cifrado
|   +-- NOTARIO.md               # Sellado blockchain
|   +-- IMPLEMENTACION.md        # Wrappers y ejemplos
+-- schemas/
|   +-- s-contract-request.json  # JSON Schema para requests (v2.1)
|   +-- s-contract-response.json # JSON Schema para responses (v2.1)
+-- m-contracts/
|   +-- CLASSIFIER.json          # M-CONTRACT clasificador
|   +-- OCR_CORE.json            # M-CONTRACT OCR
|   +-- ASR_ENGINE.json          # M-CONTRACT ASR
|   +-- ...                      # (18 modulos total)
+-- db-schemas/                  # NUEVO: Schemas PostgreSQL
|   +-- 00_types.sql             # Tipos enumerados
|   +-- 01_hst_tags.sql          # Sistema de etiquetas HST
|   +-- 02_task_manager.sql      # Gestor de tareas
|   +-- 03_work_log.sql          # Log de trabajo
|   +-- 04_ai_context.sql        # Contexto para IA
|   +-- 05_ai_requests.sql       # Log de requests IA
+-- archive/                     # Versiones obsoletas

Documentos Principales

Documento	Descripcion	Prioridad
S-CONTRACT.md	Especificacion del contrato comun v2.0	LEER PRIMERO
MODULOS_IA.md	Catalogo de los 18 modulos GRACE	Alta
ARQUITECTURA.md	Vision arquitectonica del sistema	Alta
HST_API.md	API de etiquetas HST v2.0 (tzrtech.org)	Alta
SENTINEL.md	Sistema de auditoria dual (LIGHT/DEEP)	Media
KEY_VAULT.md	Gestion de llaves y cifrado	Media
NOTARIO.md	Sellado blockchain	Media
IMPLEMENTACION.md	Wrappers Python/JS y ejemplos n8n	Referencia
db-schemas/README.md	Schemas PostgreSQL compartidos	Alta

Database Schemas (db-schemas/)

Schemas PostgreSQL compartidos por todos los componentes del ecosistema:

Schema	Descripción
`hst_tags`	Sistema de etiquetas unificado (HST/EMP/HSU/PJT)
`task_manager`	Proyectos, milestones, bloques y tareas
`task_work_log`	Log de archivos entrantes/salientes
`task_contexts`	Contexto enviado a servicios IA
`task_ai_requests`	Log de todas las requests a IA

Ver db-schemas/README.md para documentación completa.

Conceptos Clave

S-CONTRACT (Contrato del Sistema)

Marco general que define:

Estructura de requests/responses
Trazabilidad (trace_id, step_id, idempotency_key)
Perfiles FULL/LITE
Logging (SYS_LOG)
Seguridad y cifrado

M-CONTRACT (Contrato de Modulo)

Cada modulo extiende S-CONTRACT con:

Schemas de input/output especificos
Cadena de fallback
Metricas de calidad baseline
Providers disponibles

Perfiles

Perfil	Uso	Campos
FULL	Flujos criticos, auditoria completa	Todos
LITE	Operaciones rapidas, alto volumen	Minimos

Status Codes

SUCCESS - Ejecucion completa
PARTIAL - Resultado incompleto pero usable
ERROR - Fallo no recuperable
TIMEOUT - Excedio TTL
FALLBACK - Exito con modulo alternativo

Los 18 Modulos GRACE

Familia	Modulos
VISION	IMG_PREPROCESS, PDF_SCANNER, OCR_CORE
VOZ	ASR_ENGINE, TTS_ENGINE
IDENTIDAD	FACE_VECTOR, ID_CONSOLIDATION, AVATAR_GEN
SEMANTICA	EMBEDDINGS, SUMMARIZER, TASK_EXTRACTOR, CLASSIFIER, SIMILARITY
UTILIDADES	FIELD_EXTRACTOR, HASHER, INPUT_NORMALIZER, OUTPUT_ADAPTER, LANG_DETECT

Ejemplo Rapido

Request LITE

{
  "contract_version": "2.0",
  "profile": "LITE",
  "envelope": {
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "a1b2c3d4e5f6..."
  },
  "routing": {"module": "CLASSIFIER"},
  "context": {"lang": "es", "mode": "strict"},
  "payload": {
    "type": "text",
    "encoding": "utf-8",
    "content": "Factura de Telefonica por 45.99 EUR"
  }
}

Response

{
  "contract_version": "2.0",
  "profile": "LITE",
  "envelope": {"trace_id": "550e8400-...", "idempotency_key": "a1b2c3d4..."},
  "status": {"code": "SUCCESS", "provider_used": "groq"},
  "result": {
    "schema": "classifier_output_v1",
    "data": {"category": "FINANZAS", "confidence": 0.98}
  },
  "quality": {"confidence": 0.98, "coverage": 1.0},
  "errors": []
}

Historial de Versiones

Version	Fecha	Cambios
1.0	2025-12-01	Version inicial
1.1	2025-12-01	Jerarquia S/M-CONTRACT
1.2	2025-12-01	Consolidacion, modularizacion
2.0	2025-12-18	Nomenclatura GRACE, reorganizacion repo
2.1	2025-12-18	Modos de despliegue (EXTERNAL/SELF_HOSTED/SEMI), db-schemas

Repositorios Relacionados

deck - Servidor central, iniciador de conexiones
grace - Capa de procesamiento IA
penny - Asistente de voz real-time
the-factory - Procesamiento documental
mason - Constructor de prompts
hst - Sistema de etiquetas HST

Sistema GRACE - "Alfred Decide, GRACE Transforma"

Hook test Wed Dec 24 00:21:51 UTC 2025