tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
1b392803fdc033ed34ee09d466b0eead8599d7a3
system-docs/v4-archive/contratos-comunes/docs/S-CONTRACT.md

1126 lines
33 KiB
Markdown
Raw Normal View History

Archive: System v4 - Estado al 2024-12-24
2025-12-24 17:28:34 +00:00
# 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"*
Reference in New Issue Copy Permalink