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
ARCHITECT 1b392803fd Archive: System v4 - Estado al 2024-12-24
2025-12-24 17:28:34 +00:00

33 KiB
Raw Blame History

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:

{
  "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

{
  "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

{
  "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)

{
  "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:

{
  "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

{
  "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)

{
  "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) 
{
  "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 
{
  "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:

{
  "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:

{
  "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:

# 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

"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

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 View Git Blame Copy Permalink