1126 lines
33 KiB
Markdown
1126 lines
33 KiB
Markdown
# CONTRATO COMUN DEL SISTEMA (S-CONTRACT)
|
|
**Version:** 2.1
|
|
**Estado:** Enterprise Standard - Implementacion Ready
|
|
**Filosofia Base:** Interoperabilidad Total - Trazabilidad Absoluta - Resiliencia Hibrida - Privacidad por Diseno
|
|
|
|
---
|
|
|
|
# Historial de Versiones
|
|
|
|
| Version | Fecha | Cambios Principales |
|
|
|---------|-------|---------------------|
|
|
| 1.0 | 2025-12-01 | Version inicial: contrato unico, SENTINEL, SYS_LOG |
|
|
| 1.1 | 2025-12-01 | Jerarquia S/M-CONTRACT, perfiles FULL/LITE, batch, seguridad |
|
|
| 1.2 | 2025-12-01 | Consolidacion completa, modularizacion documental |
|
|
| 2.0 | 2025-12-18 | Nomenclatura actualizada (JARVIS -> GRACE), reorganizacion repo |
|
|
| 2.1 | 2025-12-18 | Modos de despliegue, context extendido (system_instruction, datasets, tags, ambiente) |
|
|
|
|
## Cambios clave v2.0 -> v2.1
|
|
|
|
1. **Seccion 5: Modos de Despliegue y Conectividad** - Nueva seccion que define:
|
|
- DECK como unico iniciador de conexiones
|
|
- Tres modos: `EXTERNAL`, `SELF_HOSTED`, `SEMI`
|
|
- Bloque `deployment` en requests
|
|
- Gestion de credenciales desde DECK
|
|
- Comportamiento especifico por servicio (GRACE, PENNY, THE FACTORY)
|
|
|
|
2. **Nuevo bloque `deployment`** en request para especificar modo de operacion.
|
|
|
|
3. **Nuevo campo `deployment_used`** en response para indicar que modo/proveedor se uso.
|
|
|
|
4. **Bloque `context` extendido** con campos para IA:
|
|
- `system_instruction`: Prompt/instruccion del sistema
|
|
- `datasets[]`: Array de datasets (knowledge, examples, rules, vocabulary, context, persona)
|
|
- `tags{}`: Etiquetas HST por grupo (hst, hsu, emp, pjt)
|
|
- `ambiente{}`: Variables de contexto ambiental (timezone, locale, currency, session_type)
|
|
|
|
5. **Glosario ampliado** con terminos de despliegue y servicios.
|
|
|
|
## Cambios clave v1.2 -> v2.0
|
|
|
|
1. **Nomenclatura actualizada** - Sistema cognitivo renombrado de JARVIS a GRACE.
|
|
|
|
2. **Reorganizacion documental** - Estructura simplificada:
|
|
- `S-CONTRACT.md` (este documento) - Marco general
|
|
- `SENTINEL.md` - Sistema de auditoria
|
|
- `IMPLEMENTACION.md` - Wrappers y ejemplos
|
|
- `KEY_VAULT.md` - Gestion de llaves
|
|
- `NOTARIO.md` - Sellado blockchain
|
|
- `MODULOS_IA.md` - Catalogo de 18 modulos
|
|
- `ARQUITECTURA.md` - Vision arquitectonica
|
|
|
|
3. **Archivado de versiones anteriores** - Documentos legacy movidos a `archive/`.
|
|
|
|
---
|
|
|
|
# 1. Proposito del Contrato Comun
|
|
|
|
El Contrato Comun es la **interfaz universal jerarquica** que garantiza:
|
|
|
|
```
|
|
+---------------------------------------------------------------------+
|
|
| PRINCIPIO FUNDAMENTAL |
|
|
| |
|
|
| "Un modulo que no cumple el contrato, no existe para Alfred" |
|
|
+---------------------------------------------------------------------+
|
|
```
|
|
|
|
- **Interoperabilidad**: Todos los modulos hablan un lenguaje compatible.
|
|
- **Trazabilidad**: Logging consistente en todo el ecosistema.
|
|
- **Intercambiabilidad**: Anadir o sustituir modulos sin romper el sistema.
|
|
- **Privacidad**: No datos flotantes, cifrado por diseno.
|
|
|
|
---
|
|
|
|
# 2. Jerarquia de Contratos
|
|
|
|
## 2.1 Arquitectura de Tres Niveles
|
|
|
|
```
|
|
+---------------------------------------------------------------------+
|
|
| S-CONTRACT (Sistema) |
|
|
| Marco general: trazas, routing, contexto, seguridad |
|
|
+---------------------------------------------------------------------+
|
|
|
|
|
+-------------------+-------------------+
|
|
| | |
|
|
v v v
|
|
+-----------------+ +-----------------+ +-----------------+
|
|
| M-CONTRACT | | M-CONTRACT | | M-CONTRACT |
|
|
| CLASSIFIER | | OCR_CORE | | ASR_ENGINE |
|
|
| | | | | |
|
|
| - schema_input | | - schema_input | | - schema_input |
|
|
| - schema_output | | - schema_output | | - schema_output |
|
|
| - perfiles | | - perfiles | | - perfiles |
|
|
| - latencias | | - latencias | | - latencias |
|
|
+-----------------+ +-----------------+ +-----------------+
|
|
|
|
|
v
|
|
+-----------------+
|
|
| PERFILES |
|
|
| FULL | LITE |
|
|
+-----------------+
|
|
```
|
|
|
|
## 2.2 S-CONTRACT (Contrato General del Sistema)
|
|
|
|
Define los conceptos y campos minimos obligatorios:
|
|
- Trazas (`envelope`)
|
|
- Enrutamiento (`routing`)
|
|
- Contexto (`context`)
|
|
- Carga util (`payload`)
|
|
- Almacenamiento (`storage`)
|
|
- Procesamiento por lotes (`batch`)
|
|
- Seguridad (`security`)
|
|
- Calidad (`quality`)
|
|
- Auditoria (`audit`)
|
|
|
|
## 2.3 M-CONTRACT (Contrato de Modulo)
|
|
|
|
Cada modulo declara su **propio contrato** que extiende el S-CONTRACT:
|
|
|
|
```json
|
|
{
|
|
"module": "CLASSIFIER",
|
|
"version": "1.0",
|
|
"extends": "S-CONTRACT-2.0",
|
|
"profiles_supported": ["FULL", "LITE"],
|
|
"capabilities": {
|
|
"payload_types": ["text"],
|
|
"max_input_tokens": 8000,
|
|
"expected_latency_ms": 500,
|
|
"batch_support": true,
|
|
"batch_max_items": 100
|
|
},
|
|
"schemas": {
|
|
"input": "classifier_input_v1",
|
|
"output": "classifier_output_v1"
|
|
},
|
|
"fallback_chain": ["CLASSIFIER_LOCAL", "CLASSIFIER_GROQ", "CLASSIFIER_OPENAI"],
|
|
"quality_baseline": {
|
|
"min_confidence": 0.7,
|
|
"expected_confidence": 0.9
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# 3. Perfiles de Contrato: FULL vs LITE
|
|
|
|
## 3.1 Comparativa de Perfiles
|
|
|
|
| Aspecto | FULL | LITE |
|
|
|---------|------|------|
|
|
| **Uso tipico** | Flujos criticos, auditoria | Operaciones rapidas |
|
|
| **Trazabilidad** | Completa (todos los campos) | Basica (trace_id + idempotency) |
|
|
| **Pasos intermedios** | Persistidos | Opcionales |
|
|
| **Auditoria SENTINEL** | LIGHT + DEEP | Solo LIGHT |
|
|
| **Consolidacion blockchain** | Si | No |
|
|
| **Overhead** | ~2KB por request | ~200B por request |
|
|
|
|
## 3.2 Perfil FULL
|
|
|
|
Orientado a:
|
|
- Flujos largos y complejos
|
|
- Procesos criticos de negocio
|
|
- Auditoria SENTINEL-LIGHT/DEEP completa
|
|
- Consolidacion en blockchain
|
|
|
|
**Campos obligatorios**: Todos los bloques del S-CONTRACT.
|
|
|
|
## 3.3 Perfil LITE
|
|
|
|
Orientado a:
|
|
- Clasificaciones simples
|
|
- Embeddings de texto
|
|
- Utilidades rapidas
|
|
- Alto volumen / baja latencia
|
|
|
|
**Campos obligatorios minimos**:
|
|
|
|
| Campo | Obligatorio | Motivo |
|
|
|-------|-------------|--------|
|
|
| `contract_version` | Si | Compatibilidad |
|
|
| `profile` | Si | Identificacion |
|
|
| `envelope.trace_id` | Si | Trazabilidad minima |
|
|
| `envelope.idempotency_key` | Si | Evitar reprocesamiento |
|
|
| `routing.module` | Si | Destino |
|
|
| `payload` | Si | Datos a procesar |
|
|
| `context.lang` | Opcional | Idioma |
|
|
| `context.mode` | Opcional | Modo de operacion |
|
|
|
|
---
|
|
|
|
# 4. Especificacion del Contrato (v2.0)
|
|
|
|
## 4.1 REQUEST - Perfil FULL
|
|
|
|
```json
|
|
{
|
|
"contract_version": "2.0",
|
|
"profile": "FULL",
|
|
|
|
"envelope": {
|
|
"trace_id": "uuid-v4-global",
|
|
"parent_trace_id": "uuid-v4-padre|null",
|
|
"step_id": "uuid-v4-paso-actual",
|
|
"step_index": 1,
|
|
"total_steps": 5,
|
|
"idempotency_key": "sha256-del-input",
|
|
"timestamp_init": "2025-12-18T10:30:00.000Z",
|
|
"ttl_ms": 30000,
|
|
"provider_timeout_ms": 15000
|
|
},
|
|
|
|
"routing": {
|
|
"module": "CLASSIFIER",
|
|
"version": "1.0",
|
|
"provider_preference": ["local", "groq", "openrouter"],
|
|
"fallback_chain": ["CLASSIFIER_LOCAL", "CLASSIFIER_GROQ", "CLASSIFIER_OPENAI"],
|
|
"max_fallback_level": 2
|
|
},
|
|
|
|
"context": {
|
|
"lang": "es",
|
|
"mode": "strict",
|
|
"pii_filter": true,
|
|
"bandera_id": "uuid-jurisdiccion",
|
|
"player_id": "uuid-actor",
|
|
"method_hash": "sha256-metodo-activo",
|
|
"human_readable": "Clasificacion de email cliente-001",
|
|
|
|
"system_instruction": "Clasifica el contenido segun taxonomia HST...",
|
|
"datasets": [
|
|
{"codigo": "DS_TAXONOMY", "tipo": "vocabulary", "contenido": "..."}
|
|
],
|
|
"tags": {
|
|
"hst": ["h_maestro_1", "h_maestro_2"],
|
|
"hsu": [],
|
|
"emp": [],
|
|
"pjt": []
|
|
},
|
|
"ambiente": {
|
|
"timezone": "Europe/Madrid",
|
|
"locale": "es-ES",
|
|
"currency": "EUR",
|
|
"session_type": "batch"
|
|
}
|
|
},
|
|
|
|
"payload": {
|
|
"type": "text|image|audio|document|structured",
|
|
"encoding": "utf-8|base64|url",
|
|
"content": "...",
|
|
"content_hash": "sha256-del-contenido",
|
|
"schema_expected": "nombre-del-schema-salida"
|
|
},
|
|
|
|
"batch": {
|
|
"is_batch": false,
|
|
"batch_id": null,
|
|
"item_index": null,
|
|
"items_total": 1,
|
|
"batch_mode": "SEQUENTIAL|PARALLEL"
|
|
},
|
|
|
|
"storage": {
|
|
"input_location": "internal|external|local_ephemeral|client_side",
|
|
"input_ref": "hostinger://path|s3://bucket/key",
|
|
"output_location": "internal|external",
|
|
"output_ref": "hostinger://path|s3://bucket/key",
|
|
"persist_intermediate": true,
|
|
"retention_days": 30
|
|
},
|
|
|
|
"security": {
|
|
"encryption_profile": "NONE|E2E_BASIC|E2E_STRICT",
|
|
"data_sensitivity": "LOW|MEDIUM|HIGH|SECRET",
|
|
"key_vault_ref": "kv://profile/uuid",
|
|
"pii_detected": false,
|
|
"gdpr_relevant": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### Campos del Envelope
|
|
|
|
| Campo | Tipo | Obligatorio | Descripcion |
|
|
|-------|------|-------------|-------------|
|
|
| `trace_id` | UUID v4 | Si | ID unico de la ejecucion completa |
|
|
| `parent_trace_id` | UUID v4 / null | No | Referencia al proceso padre |
|
|
| `step_id` | UUID v4 | Si | ID unico de este paso especifico |
|
|
| `step_index` | integer | Si | Posicion en la cadena (1-indexed) |
|
|
| `total_steps` | integer | No | Total estimado de pasos |
|
|
| `idempotency_key` | SHA256 | Si | Hash del contenido para deduplicacion |
|
|
| `timestamp_init` | ISO8601 | Si | Momento de creacion |
|
|
| `ttl_ms` | integer | No | Tiempo maximo de vida (default: 30000) |
|
|
| `provider_timeout_ms` | integer | No | Timeout especifico del proveedor |
|
|
|
|
### Campos de Routing
|
|
|
|
| Campo | Tipo | Obligatorio | Descripcion |
|
|
|-------|------|-------------|-------------|
|
|
| `module` | string | Si | Nombre del modulo destino |
|
|
| `version` | semver | No | Version del M-CONTRACT |
|
|
| `provider_preference` | array | No | Orden de preferencia |
|
|
| `fallback_chain` | array | No | Modulos alternativos |
|
|
| `max_fallback_level` | integer | No | Maximo nivel de degradacion |
|
|
|
|
### Tipos de Storage Location
|
|
|
|
| Tipo | Descripcion | TTL Default | Verificacion |
|
|
|------|-------------|-------------|--------------|
|
|
| `internal` | Hostinger/Nextcloud | 90 dias | Hash al guardar |
|
|
| `external` | S3/GCS/Azure | 1 ano | Hash + versioning |
|
|
| `local_ephemeral` | Temporal destruible | 24 horas | Hash en memoria |
|
|
| `client_side` | Dispositivo usuario | N/A | Hash obligatorio en request |
|
|
|
|
---
|
|
|
|
## 4.2 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 clasificar"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Regla de oro**: Un modulo que soporta LITE **no puede exigir** campos adicionales.
|
|
|
|
---
|
|
|
|
## 4.3 RESPONSE - Universal (FULL/LITE)
|
|
|
|
```json
|
|
{
|
|
"contract_version": "2.0",
|
|
"profile": "FULL|LITE",
|
|
|
|
"envelope": {
|
|
"trace_id": "uuid-v4-global",
|
|
"step_id": "uuid-v4-paso-actual",
|
|
"step_index": 1,
|
|
"idempotency_key": "sha256-del-input",
|
|
"timestamp_init": "2025-12-18T10:30:00.000Z",
|
|
"timestamp_end": "2025-12-18T10:30:00.450Z"
|
|
},
|
|
|
|
"status": {
|
|
"code": "SUCCESS|PARTIAL|ERROR|TIMEOUT|FALLBACK",
|
|
"fallback_level_used": 0,
|
|
"provider_used": "local|groq|openrouter",
|
|
"module_instance": "CLASSIFIER_GROQ_V1"
|
|
},
|
|
|
|
"result": {
|
|
"schema": "classifier_output_v1",
|
|
"data": {
|
|
"category": "FINANZAS",
|
|
"confidence": 0.98,
|
|
"subcategory": "FACTURA",
|
|
"tags": ["proveedor", "mensual"]
|
|
}
|
|
},
|
|
|
|
"quality": {
|
|
"confidence": 0.98,
|
|
"coverage": 1.0,
|
|
"tokens_input": 150,
|
|
"tokens_output": 45,
|
|
"validation_passed": true,
|
|
"schema_valid": true
|
|
},
|
|
|
|
"metadata": {
|
|
"model_id": "llama-3-70b-instruct",
|
|
"model_version": "2024-03",
|
|
"processing_ms": 450,
|
|
"queue_wait_ms": 12,
|
|
"retries": 0,
|
|
"cost_units": 0.0012
|
|
},
|
|
|
|
"storage": {
|
|
"output_persisted": true,
|
|
"output_ref": "hostinger://processed/2025/12/18/uuid.json",
|
|
"output_hash": "sha256-del-output",
|
|
"intermediate_refs": []
|
|
},
|
|
|
|
"audit": {
|
|
"sentinel_light_checked": false,
|
|
"sentinel_deep_checked": false,
|
|
"sentinel_findings_ref": null,
|
|
"blockchain_pending": false,
|
|
"blockchain_tx_ref": null,
|
|
"notario_batch_id": null
|
|
},
|
|
|
|
"errors": [],
|
|
"warnings": []
|
|
}
|
|
```
|
|
|
|
### Codigos de Status
|
|
|
|
| Codigo | Significado | Accion Alfred | Logging |
|
|
|--------|-------------|---------------|---------|
|
|
| `SUCCESS` | Ejecucion completa y valida | Continuar flujo | INFO |
|
|
| `PARTIAL` | Resultado incompleto pero usable | Evaluar `coverage` | WARN |
|
|
| `ERROR` | Fallo no recuperable | Activar fallback o abortar | ERROR |
|
|
| `TIMEOUT` | Excedio TTL o provider_timeout | Activar fallback | WARN |
|
|
| `FALLBACK` | Exito usando modulo alternativo | Continuar + log | INFO |
|
|
|
|
---
|
|
|
|
# 5. Modos de Despliegue y Conectividad
|
|
|
|
## 5.1 Principio Fundamental: DECK como Iniciador
|
|
|
|
```
|
|
+---------------------------------------------------------------------+
|
|
| PRINCIPIO DE CONECTIVIDAD |
|
|
| |
|
|
| "DECK inicia TODAS las conexiones. Los servicios son stateless. |
|
|
| Cada request lleva su contexto completo. Nada se asume." |
|
|
+---------------------------------------------------------------------+
|
|
```
|
|
|
|
DECK (el servidor personal del usuario) es el **unico punto que inicia conexiones**:
|
|
|
|
- DECK → PENNY (sesiones de voz)
|
|
- DECK → GRACE (procesamiento cognitivo via Alfred)
|
|
- DECK → THE FACTORY (generacion de contenido)
|
|
|
|
Los servicios **nunca** inician conexiones hacia DECK. Son receptores pasivos que:
|
|
- Reciben contexto completo en cada request
|
|
- Procesan sin estado persistente
|
|
- Devuelven resultado y olvidan
|
|
|
|
## 5.2 Modos de Despliegue
|
|
|
|
Cada servicio puede operar en tres modos:
|
|
|
|
| Modo | Codigo | Descripcion |
|
|
|------|--------|-------------|
|
|
| **Externo** | `EXTERNAL` | Solo APIs comerciales (OpenAI, Anthropic, etc.) |
|
|
| **Autoalojado** | `SELF_HOSTED` | Solo infraestructura propia (RunPod, servidor local) |
|
|
| **Semi-automatico** | `SEMI` | Hibrido con fallback automatico |
|
|
|
|
### 5.2.1 Modo EXTERNAL
|
|
|
|
```
|
|
DECK ──────────────────────────────► APIs Comerciales
|
|
(OpenAI, Anthropic, Groq, etc.)
|
|
```
|
|
|
|
- Sin infraestructura propia
|
|
- Pago por uso a proveedores
|
|
- Maxima disponibilidad, minimo mantenimiento
|
|
- Datos salen del control del usuario
|
|
|
|
### 5.2.2 Modo SELF_HOSTED
|
|
|
|
```
|
|
DECK ──────────────────────────────► Infraestructura Propia
|
|
(RunPod, Modal, servidor local)
|
|
```
|
|
|
|
- Control total de datos
|
|
- Coste fijo o por uso de GPU
|
|
- Requiere mantenimiento
|
|
- Zero datos a terceros
|
|
|
|
### 5.2.3 Modo SEMI (Semi-automatico)
|
|
|
|
```
|
|
DECK ─────┬────────────────────────► Infraestructura Propia (prioridad)
|
|
│ │
|
|
│ │ (si falla/timeout)
|
|
│ ▼
|
|
└────────────────────────► APIs Comerciales (fallback)
|
|
```
|
|
|
|
- Intenta primero autoalojado
|
|
- Fallback a externo si falla
|
|
- Balance entre control y disponibilidad
|
|
- Configuracion de preferencias por servicio
|
|
|
|
## 5.3 Configuracion de Deployment en Request
|
|
|
|
El bloque `deployment` es **opcional** y define el modo de operacion:
|
|
|
|
```json
|
|
{
|
|
"contract_version": "2.0",
|
|
"profile": "FULL",
|
|
|
|
"deployment": {
|
|
"mode": "SEMI",
|
|
"tier_preference": ["SELF_HOSTED", "EXTERNAL"],
|
|
"self_hosted": {
|
|
"endpoint": "https://runpod.example.com/v2/abc123/runsync",
|
|
"timeout_ms": 30000,
|
|
"retry_on_failure": true
|
|
},
|
|
"external": {
|
|
"providers_allowed": ["groq", "openai", "anthropic"],
|
|
"providers_blocked": [],
|
|
"max_cost_per_request": 0.10
|
|
},
|
|
"credentials_ref": "kv://deck/credentials/grace"
|
|
},
|
|
|
|
"envelope": {...},
|
|
"routing": {...},
|
|
"payload": {...}
|
|
}
|
|
```
|
|
|
|
### Campos de Deployment
|
|
|
|
| Campo | Tipo | Obligatorio | Descripcion |
|
|
|-------|------|-------------|-------------|
|
|
| `mode` | enum | Si | `EXTERNAL`, `SELF_HOSTED`, `SEMI` |
|
|
| `tier_preference` | array | No | Orden de preferencia de tiers |
|
|
| `self_hosted.endpoint` | URL | Condicional | Endpoint del servicio autoalojado |
|
|
| `self_hosted.timeout_ms` | integer | No | Timeout para autoalojado |
|
|
| `self_hosted.retry_on_failure` | boolean | No | Reintentar antes de fallback |
|
|
| `external.providers_allowed` | array | No | Lista blanca de proveedores |
|
|
| `external.providers_blocked` | array | No | Lista negra de proveedores |
|
|
| `external.max_cost_per_request` | decimal | No | Limite de coste por request |
|
|
| `credentials_ref` | string | No | Referencia a credenciales en Key Vault |
|
|
|
|
## 5.4 Credenciales desde DECK
|
|
|
|
DECK **siempre** proporciona las credenciales necesarias. Los servicios **nunca** almacenan credenciales.
|
|
|
|
### Opcion A: Referencia a Key Vault
|
|
|
|
```json
|
|
{
|
|
"deployment": {
|
|
"mode": "SEMI",
|
|
"credentials_ref": "kv://deck/credentials/grace"
|
|
}
|
|
}
|
|
```
|
|
|
|
El servicio resuelve la referencia contra el Key Vault de DECK.
|
|
|
|
### Opcion B: Credenciales en Request (conexiones seguras)
|
|
|
|
```json
|
|
{
|
|
"deployment": {
|
|
"mode": "EXTERNAL",
|
|
"credentials": {
|
|
"openai": {"api_key": "sk-..."},
|
|
"anthropic": {"api_key": "sk-ant-..."},
|
|
"groq": {"api_key": "gsk_..."}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Solo permitido con `encryption_profile: E2E_STRICT` y conexiones mTLS.
|
|
|
|
## 5.5 Comportamiento por Servicio
|
|
|
|
### GRACE (Capa Cognitiva)
|
|
|
|
| Modo | Tier 1 | Tier 2 |
|
|
|------|--------|--------|
|
|
| `EXTERNAL` | - | APIs comerciales |
|
|
| `SELF_HOSTED` | RunPod Serverless, Local | - |
|
|
| `SEMI` | RunPod Serverless → | APIs comerciales (fallback) |
|
|
|
|
```json
|
|
{
|
|
"routing": {
|
|
"module": "ASR_ENGINE",
|
|
"fallback_chain": ["ASR_FASTER_WHISPER", "ASR_GROQ", "ASR_OPENAI"]
|
|
},
|
|
"deployment": {
|
|
"mode": "SEMI",
|
|
"tier_preference": ["SELF_HOSTED", "EXTERNAL"],
|
|
"self_hosted": {
|
|
"endpoint": "https://api.runpod.ai/v2/asr-whisper/runsync"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### PENNY (Asistente de Voz)
|
|
|
|
| Modo | ASR | LLM | TTS |
|
|
|------|-----|-----|-----|
|
|
| `EXTERNAL` | Groq/OpenAI | Claude/GPT | ElevenLabs |
|
|
| `SELF_HOSTED` | Faster Whisper | Qwen/Llama | XTTS-v2 |
|
|
| `SEMI` | Faster Whisper → Groq | Qwen → Claude | XTTS → ElevenLabs |
|
|
|
|
```json
|
|
{
|
|
"type": "session_start",
|
|
"deployment": {
|
|
"mode": "SEMI",
|
|
"components": {
|
|
"asr": {"preference": ["SELF_HOSTED", "EXTERNAL"]},
|
|
"llm": {"preference": ["SELF_HOSTED", "EXTERNAL"]},
|
|
"tts": {"preference": ["SELF_HOSTED", "EXTERNAL"]}
|
|
},
|
|
"self_hosted": {
|
|
"endpoint": "wss://runpod-penny.example.com/ws/voice"
|
|
},
|
|
"external": {
|
|
"llm_provider": "anthropic",
|
|
"tts_provider": "elevenlabs"
|
|
}
|
|
},
|
|
"planos": {...}
|
|
}
|
|
```
|
|
|
|
### THE FACTORY (Generacion de Contenido)
|
|
|
|
| Modo | Generacion | Post-procesado |
|
|
|------|------------|----------------|
|
|
| `EXTERNAL` | APIs comerciales (Midjourney, DALL-E) | APIs |
|
|
| `SELF_HOSTED` | RunPod (SDXL, Flux) | Local |
|
|
| `SEMI` | RunPod → | APIs comerciales (fallback) |
|
|
|
|
## 5.6 Response con Informacion de Deployment
|
|
|
|
El response incluye que modo/proveedor se uso:
|
|
|
|
```json
|
|
{
|
|
"status": {
|
|
"code": "SUCCESS",
|
|
"deployment_used": {
|
|
"mode": "SEMI",
|
|
"tier_used": "SELF_HOSTED",
|
|
"provider_used": "runpod",
|
|
"endpoint_used": "https://api.runpod.ai/v2/asr-whisper/runsync",
|
|
"fallback_activated": false
|
|
}
|
|
},
|
|
"result": {...}
|
|
}
|
|
```
|
|
|
|
Si hubo fallback:
|
|
|
|
```json
|
|
{
|
|
"status": {
|
|
"code": "FALLBACK",
|
|
"deployment_used": {
|
|
"mode": "SEMI",
|
|
"tier_used": "EXTERNAL",
|
|
"provider_used": "groq",
|
|
"fallback_activated": true,
|
|
"fallback_reason": "SELF_HOSTED_TIMEOUT",
|
|
"original_tier": "SELF_HOSTED",
|
|
"original_error": "Timeout after 30000ms"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 5.7 Configuracion Default en DECK
|
|
|
|
DECK mantiene configuracion por defecto para cada servicio:
|
|
|
|
```yaml
|
|
# deck/config/deployment.yaml
|
|
|
|
defaults:
|
|
mode: SEMI
|
|
tier_preference: [SELF_HOSTED, EXTERNAL]
|
|
|
|
services:
|
|
grace:
|
|
mode: SEMI
|
|
self_hosted:
|
|
endpoint: https://api.runpod.ai/v2/${RUNPOD_GRACE_ID}/runsync
|
|
timeout_ms: 30000
|
|
external:
|
|
providers_allowed: [groq, openai, anthropic]
|
|
|
|
penny:
|
|
mode: SEMI
|
|
self_hosted:
|
|
endpoint: wss://${RUNPOD_PENNY_HOST}/ws/voice
|
|
timeout_ms: 5000
|
|
external:
|
|
llm_provider: anthropic
|
|
tts_provider: elevenlabs
|
|
|
|
factory:
|
|
mode: SEMI
|
|
self_hosted:
|
|
endpoint: https://api.runpod.ai/v2/${RUNPOD_FACTORY_ID}/runsync
|
|
timeout_ms: 120000
|
|
external:
|
|
providers_allowed: [replicate, stability]
|
|
|
|
credentials:
|
|
ref: kv://deck/credentials
|
|
# O inline (solo desarrollo):
|
|
# groq_key: gsk_...
|
|
# openai_key: sk-...
|
|
```
|
|
|
|
---
|
|
|
|
# 6. Batch Processing
|
|
|
|
## 6.1 Filosofia
|
|
|
|
```
|
|
+---------------------------------------------------------------------+
|
|
| PRINCIPIO DE BATCH |
|
|
| |
|
|
| "Todos los datos entran solidos y se procesan solidos. |
|
|
| Nunca datos flotantes. Cada item tiene su trace_id." |
|
|
+---------------------------------------------------------------------+
|
|
```
|
|
|
|
## 6.2 Campos de Batch
|
|
|
|
```json
|
|
"batch": {
|
|
"is_batch": true,
|
|
"batch_id": "uuid-batch",
|
|
"item_index": 15,
|
|
"items_total": 120,
|
|
"batch_mode": "PARALLEL",
|
|
"batch_priority": "NORMAL|HIGH|LOW",
|
|
"batch_deadline": "2025-12-18T18:00:00.000Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# 7. Sistema de Logging (SYS_LOG)
|
|
|
|
## 7.1 Filosofia
|
|
|
|
```
|
|
+---------------------------------------------------------------------+
|
|
| PRINCIPIO DE LOGGING |
|
|
| |
|
|
| "Si no esta en el log, no ocurrio. Si ocurrio, esta en log." |
|
|
+---------------------------------------------------------------------+
|
|
```
|
|
|
|
## 7.2 Arquitectura de Libros
|
|
|
|
```
|
|
+---------------------------------------------------------------------+
|
|
| SYS_LOG (Libro Diario) |
|
|
| Registro de TODOS los eventos del sistema |
|
|
+---------------------------------------------------------------------+
|
|
|
|
|
| (procesos exitosos)
|
|
v
|
|
+---------------------------------------------------------------------+
|
|
| SFE (Libro Mayor) |
|
|
| Solo procesos completados y validados |
|
|
+---------------------------------------------------------------------+
|
|
|
|
|
| (consolidacion periodica)
|
|
v
|
|
+---------------------------------------------------------------------+
|
|
| NOTARIO (Blockchain) |
|
|
| Sellado inmutable de registros criticos |
|
|
+---------------------------------------------------------------------+
|
|
```
|
|
|
|
## 7.3 Estructura de Tabla SYS_LOG
|
|
|
|
```sql
|
|
CREATE TABLE SYS_LOG (
|
|
-- IDENTIFICACION
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
trace_id UUID NOT NULL,
|
|
parent_trace_id UUID,
|
|
step_id UUID NOT NULL UNIQUE,
|
|
idempotency_key CHAR(64) NOT NULL,
|
|
|
|
-- SECUENCIA Y TIPO
|
|
step_index INTEGER NOT NULL,
|
|
step_type VARCHAR(20) NOT NULL,
|
|
profile VARCHAR(10) DEFAULT 'FULL',
|
|
|
|
-- BATCH
|
|
batch_id UUID,
|
|
batch_item_index INTEGER,
|
|
batch_items_total INTEGER,
|
|
|
|
-- TEMPORALIDAD
|
|
timestamp_created TIMESTAMPTZ DEFAULT NOW(),
|
|
timestamp_started TIMESTAMPTZ,
|
|
timestamp_completed TIMESTAMPTZ,
|
|
duration_ms INTEGER,
|
|
queue_wait_ms INTEGER,
|
|
|
|
-- MODULO Y PROVEEDOR
|
|
module_name VARCHAR(50) NOT NULL,
|
|
module_version VARCHAR(20),
|
|
provider_requested VARCHAR(50),
|
|
provider_used VARCHAR(50),
|
|
fallback_level INTEGER DEFAULT 0,
|
|
model_id VARCHAR(100),
|
|
model_version VARCHAR(50),
|
|
|
|
-- ESTADO Y ERRORES
|
|
status_code VARCHAR(20) NOT NULL,
|
|
error_code VARCHAR(50),
|
|
error_message TEXT,
|
|
retries INTEGER DEFAULT 0,
|
|
|
|
-- PAYLOAD (Referencias, NO datos crudos)
|
|
input_hash CHAR(64) NOT NULL,
|
|
input_ref TEXT NOT NULL,
|
|
input_size_bytes BIGINT,
|
|
input_type VARCHAR(20),
|
|
output_hash CHAR(64),
|
|
output_ref TEXT,
|
|
output_size_bytes BIGINT,
|
|
intermediate_refs JSONB DEFAULT '[]',
|
|
|
|
-- CALIDAD
|
|
confidence DECIMAL(5,4),
|
|
coverage DECIMAL(5,4),
|
|
tokens_input INTEGER,
|
|
tokens_output INTEGER,
|
|
validation_passed BOOLEAN,
|
|
schema_valid BOOLEAN,
|
|
|
|
-- COSTOS
|
|
cost_units DECIMAL(12,8),
|
|
cost_currency VARCHAR(3) DEFAULT 'USD',
|
|
|
|
-- CONTEXTO
|
|
bandera_id UUID,
|
|
player_id UUID,
|
|
method_hash CHAR(64),
|
|
human_readable TEXT,
|
|
|
|
-- SEGURIDAD
|
|
encryption_profile VARCHAR(20) DEFAULT 'NONE',
|
|
data_sensitivity VARCHAR(20) DEFAULT 'LOW',
|
|
key_vault_ref TEXT,
|
|
pii_detected BOOLEAN DEFAULT FALSE,
|
|
|
|
-- AUDITORIA
|
|
audit_status VARCHAR(20) DEFAULT 'PENDING',
|
|
audit_light_ts TIMESTAMPTZ,
|
|
audit_deep_ts TIMESTAMPTZ,
|
|
audit_result JSONB,
|
|
|
|
-- BLOCKCHAIN
|
|
blockchain_pending BOOLEAN DEFAULT FALSE,
|
|
blockchain_tx_ref VARCHAR(100),
|
|
notario_batch_id UUID,
|
|
|
|
-- CONSTRAINTS
|
|
CONSTRAINT valid_status CHECK (
|
|
status_code IN ('PENDING', 'RUNNING', 'SUCCESS', 'PARTIAL', 'ERROR', 'TIMEOUT', 'FALLBACK', 'CANCELLED')
|
|
),
|
|
CONSTRAINT valid_step_type CHECK (
|
|
step_type IN ('INIT', 'VALIDATE', 'ROUTE', 'TRANSFORM', 'FALLBACK', 'PERSIST', 'NOTIFY', 'COMPLETE', 'ERROR', 'AUDIT', 'CANCEL')
|
|
),
|
|
CONSTRAINT valid_profile CHECK (
|
|
profile IN ('FULL', 'LITE')
|
|
)
|
|
);
|
|
|
|
-- INDICES
|
|
CREATE INDEX idx_syslog_trace ON SYS_LOG(trace_id);
|
|
CREATE INDEX idx_syslog_created ON SYS_LOG(timestamp_created);
|
|
CREATE INDEX idx_syslog_status ON SYS_LOG(status_code);
|
|
CREATE INDEX idx_syslog_module ON SYS_LOG(module_name, timestamp_created);
|
|
CREATE INDEX idx_syslog_batch ON SYS_LOG(batch_id) WHERE batch_id IS NOT NULL;
|
|
CREATE INDEX idx_syslog_idempotency ON SYS_LOG(idempotency_key);
|
|
```
|
|
|
|
## 7.4 Tipos de Step
|
|
|
|
| Tipo | Descripcion | Duracion Tipica |
|
|
|------|-------------|-----------------|
|
|
| `INIT` | Entrada inicial al sistema | <10ms |
|
|
| `VALIDATE` | Validacion de entrada y permisos | <50ms |
|
|
| `ROUTE` | Decision de modulo y proveedor | <10ms |
|
|
| `TRANSFORM` | Procesamiento por modulo IA | 100ms-30s |
|
|
| `FALLBACK` | Activacion de modulo alternativo | <10ms |
|
|
| `PERSIST` | Escritura a almacenamiento | 50-500ms |
|
|
| `NOTIFY` | Notificacion externa | 100-2000ms |
|
|
| `COMPLETE` | Finalizacion exitosa | <10ms |
|
|
| `ERROR` | Registro de fallo | <10ms |
|
|
| `AUDIT` | Registro de auditoria SENTINEL | Variable |
|
|
|
|
---
|
|
|
|
# 8. Almacenamiento Dual
|
|
|
|
## 8.1 Estructura
|
|
|
|
### Interno (Hostinger/Nextcloud)
|
|
|
|
```
|
|
/data/
|
|
+-- original/ # Archivos crudos de entrada
|
|
| +-- YYYY/MM/DD/
|
|
+-- processed/ # Resultados finales
|
|
| +-- YYYY/MM/DD/
|
|
+-- intermediate/ # Pasos intermedios
|
|
| +-- {trace_id}/
|
|
+-- cache/ # Cache de resultados
|
|
+-- ephemeral/ # Temporal destruible (24h)
|
|
```
|
|
|
|
### Externo (S3/GCS)
|
|
|
|
```
|
|
bucket-grace-{env}/
|
|
+-- archive/ # Largo plazo (1+ anos)
|
|
+-- backup/ # Respaldos criticos
|
|
+-- heavy/ # Archivos grandes
|
|
+-- exports/ # Exportaciones para usuarios
|
|
```
|
|
|
|
## 8.2 URIs de Referencia
|
|
|
|
```
|
|
# Interno
|
|
hostinger://original/2025/12/18/abc123_factura.pdf
|
|
hostinger://processed/2025/12/18/abc123_output.json
|
|
|
|
# Externo
|
|
s3://grace-prod/archive/2025/12/abc123.tar.gz
|
|
|
|
# Key Vault
|
|
kv://production/encryption/abc123
|
|
```
|
|
|
|
---
|
|
|
|
# 9. Seguridad y Cifrado
|
|
|
|
## 9.1 Perfiles de Cifrado
|
|
|
|
| Perfil | Transporte | Reposo | Uso Tipico |
|
|
|--------|------------|--------|------------|
|
|
| `NONE` | TLS 1.3 | Sin cifrar | Datos publicos |
|
|
| `E2E_BASIC` | TLS 1.3 | AES-256 | Datos internos |
|
|
| `E2E_STRICT` | mTLS | AES-256-GCM | PII, financiero |
|
|
|
|
## 9.2 Niveles de Sensibilidad
|
|
|
|
| Nivel | Ejemplos | Cifrado Minimo | Retencion Max |
|
|
|-------|----------|----------------|---------------|
|
|
| `LOW` | Logs tecnicos | NONE | 1 ano |
|
|
| `MEDIUM` | Emails, documentos | E2E_BASIC | 90 dias |
|
|
| `HIGH` | Facturas, contratos | E2E_BASIC | 30 dias |
|
|
| `SECRET` | PII, biometria | E2E_STRICT | 7 dias |
|
|
|
|
Ver `KEY_VAULT.md` para especificacion completa.
|
|
|
|
---
|
|
|
|
# 10. Auditoria (SENTINEL)
|
|
|
|
## 10.1 Arquitectura Dual
|
|
|
|
| Componente | SENTINEL-LIGHT | SENTINEL-DEEP |
|
|
|------------|----------------|---------------|
|
|
| **Motor** | Reglas + ML local | LLM pesado (remoto) |
|
|
| **Frecuencia** | Cada 5 minutos | Cada hora + escalados |
|
|
| **Cobertura** | 100% registros | Muestreo + errores |
|
|
| **Latencia** | <100ms/registro | 2-5s/analisis |
|
|
|
|
Ver `SENTINEL.md` para especificacion completa.
|
|
|
|
---
|
|
|
|
# 11. Notario y Blockchain
|
|
|
|
## 11.1 Ciclo Basico
|
|
|
|
```
|
|
Alfred procesa -> SYS_LOG (diario)
|
|
|
|
|
SENTINEL audita -> AUDIT_RESULTS
|
|
|
|
|
NOTARIO agrupa -> Batch de sellado
|
|
|
|
|
Blockchain -> tx_ref inmutable
|
|
```
|
|
|
|
Ver `NOTARIO.md` para especificacion completa.
|
|
|
|
---
|
|
|
|
# 12. Catalogo de Modulos GRACE
|
|
|
|
| ID | Nombre | Familia | Descripcion |
|
|
|----|--------|---------|-------------|
|
|
| 1 | IMG_PREPROCESS | VISION | Normalizacion de imagenes |
|
|
| 2 | PDF_SCANNER | VISION | Limpieza de PDFs escaneados |
|
|
| 3 | OCR_CORE | VISION | Extraccion de texto |
|
|
| 4 | ASR_ENGINE | VOZ | Reconocimiento de habla |
|
|
| 5 | TTS_ENGINE | VOZ | Sintesis de voz |
|
|
| 6 | FACE_VECTOR | IDENTIDAD | Vector biometrico facial |
|
|
| 7 | ID_CONSOLIDATION | IDENTIDAD | Fusion de identidades |
|
|
| 8 | AVATAR_GEN | IDENTIDAD | Generacion de avatar |
|
|
| 9 | EMBEDDINGS | SEMANTICA | Vectorizacion semantica |
|
|
| 10 | SUMMARIZER | SEMANTICA | Resumen estructurado |
|
|
| 11 | TASK_EXTRACTOR | SEMANTICA | Extraccion de tareas |
|
|
| 12 | CLASSIFIER | SEMANTICA | Clasificacion de contenido |
|
|
| 13 | SIMILARITY | SEMANTICA | Comparacion vectorial |
|
|
| 14 | FIELD_EXTRACTOR | UTILIDADES | Extraccion de campos |
|
|
| 15 | HASHER | UTILIDADES | Generacion de hashes |
|
|
| 16 | INPUT_NORMALIZER | UTILIDADES | Normalizacion de entradas |
|
|
| 17 | OUTPUT_ADAPTER | UTILIDADES | Adaptacion de salidas |
|
|
| 18 | LANG_DETECT | UTILIDADES | Deteccion de idioma |
|
|
|
|
Ver `MODULOS_IA.md` para especificacion detallada de cada modulo.
|
|
|
|
---
|
|
|
|
# 13. Documentos Relacionados
|
|
|
|
| Documento | Contenido |
|
|
|-----------|-----------|
|
|
| `SENTINEL.md` | Sistema de auditoria completo |
|
|
| `IMPLEMENTACION.md` | Wrappers Python/JS, ejemplos |
|
|
| `KEY_VAULT.md` | Gestion de llaves y cifrado |
|
|
| `NOTARIO.md` | Sellado y consolidacion blockchain |
|
|
| `MODULOS_IA.md` | Catalogo de 18 modulos GRACE |
|
|
| `ARQUITECTURA.md` | Vision arquitectonica del sistema |
|
|
|
|
---
|
|
|
|
# 14. Checklist de Implementacion
|
|
|
|
## Para nuevos modulos (M-CONTRACT):
|
|
|
|
- [ ] Declarar perfiles soportados (FULL, LITE)
|
|
- [ ] Declarar schemas de entrada/salida
|
|
- [ ] Definir latencias esperadas y baseline de calidad
|
|
- [ ] Definir comportamiento en batch
|
|
- [ ] Implementar soporte de encryption_profile minimo E2E_BASIC
|
|
- [ ] Documentar fallback_chain
|
|
- [ ] Probar integracion con SENTINEL
|
|
|
|
## Para Alfred (orquestador):
|
|
|
|
- [ ] Soportar construccion de requests FULL/LITE
|
|
- [ ] Validar request contra S-CONTRACT antes de enviar
|
|
- [ ] Validar response antes de persistir
|
|
- [ ] Gestionar colas usando batch_id + SYS_LOG
|
|
- [ ] Evitar datos flotantes (siempre *_ref solido)
|
|
- [ ] Respetar ttl_ms y provider_timeout_ms
|
|
- [ ] Registrar TODOS los pasos en SYS_LOG
|
|
|
|
---
|
|
|
|
# 15. Glosario
|
|
|
|
| Termino | Definicion |
|
|
|---------|------------|
|
|
| **S-CONTRACT** | Contrato General del Sistema, marco comun obligatorio |
|
|
| **M-CONTRACT** | Contrato especifico de un modulo |
|
|
| **Perfil FULL** | Uso con trazabilidad y auditoria completa |
|
|
| **Perfil LITE** | Uso ligero, minimo necesario |
|
|
| **trace_id** | Identificador unico de una ejecucion completa |
|
|
| **step_id** | Identificador unico de un paso especifico |
|
|
| **idempotency_key** | Hash que permite detectar operaciones duplicadas |
|
|
| **fallback_chain** | Lista ordenada de modulos alternativos |
|
|
| **Key Vault** | Almacenamiento seguro de llaves y credenciales |
|
|
| **Libro Diario** | SYS_LOG, registro de todos los eventos |
|
|
| **Libro Mayor** | SFE, solo procesos completados y validados |
|
|
| **NOTARIO** | Modulo de consolidacion y sellado blockchain |
|
|
| **SENTINEL-LIGHT** | Auditor rapido, exhaustivo, basado en reglas |
|
|
| **SENTINEL-DEEP** | Auditor profundo, muestreo + errores, basado en LLM |
|
|
| **GRACE** | Sistema cognitivo de 18 microservicios IA |
|
|
| **DECK** | Servidor personal del usuario, inicia todas las conexiones |
|
|
| **PENNY** | Asistente personal de voz conversacional |
|
|
| **THE FACTORY** | Sistema de generacion de contenido |
|
|
| **Modo EXTERNAL** | Despliegue usando solo APIs comerciales externas |
|
|
| **Modo SELF_HOSTED** | Despliegue usando solo infraestructura propia |
|
|
| **Modo SEMI** | Despliegue hibrido con fallback automatico |
|
|
| **tier_preference** | Orden de preferencia de tiers (SELF_HOSTED, EXTERNAL) |
|
|
| **credentials_ref** | Referencia a credenciales en Key Vault de DECK |
|
|
|
|
---
|
|
|
|
**Fin del Documento S-CONTRACT - Version 2.1**
|
|
|
|
*Sistema GRACE - "Alfred Decide, GRACE Transforma"*
|