system-docs/01_ARQUITECTURA/entidades/modelo-cero.md

MODELO CERO

Tipo: Plantilla Base / Desarrollo IP: 72.62.1.113 Dominio: tzzrdeck.me

---

Rol en el Ecosistema

MODELO CERO es la plantilla base replicable del sistema. Sirve como entorno de desarrollo y experimentación antes de replicar cambios a instancias de producción (como PABLO).

Es el servidor central y punto de iniciación de todas las conexiones hacia los servicios de IA en cualquier instancia del sistema.

┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPIO MODELO CERO                               │
│                                                                 │
│   "MODELO CERO inicia TODAS las conexiones. Los servicios son         │
│    stateless. Cada request lleva su contexto completo."        │
└─────────────────────────────────────────────────────────────────┘

---

Funciones

Función	Descripción
Iniciador	Todas las llamadas a GRACE, PENNY, FACTORY se originan aquí
Gestor contexto	Envía información de contexto con cada request
Router despliegue	Decide si usar self-hosted o externos
Almacén credenciales	Gestiona API keys vía Key Vault

---

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                           MODELO CERO                                  │
│                    (Servidor Central)                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  PostgreSQL  │  │   Directus   │  │ FileBrowser  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Vaultwarden  │  │    Shlink    │  │   Addy.io    │          │
│  │ (Key Vault)  │  │              │  │              │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              DEPLOYMENT ROUTER                            │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │  │
│  │  │   GRACE     │  │   PENNY     │  │  FACTORY    │       │  │
│  │  │  Connector  │  │  Connector  │  │  Connector  │       │  │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘       │  │
│  └─────────┼────────────────┼────────────────┼───────────────┘  │
└────────────┼────────────────┼────────────────┼──────────────────┘
             │                │                │
             ▼                ▼                ▼
    ┌────────────────────────────────────────────────────┐
    │              SERVICIOS DE IA                        │
    ├────────────────────────────────────────────────────┤
    │  ┌─────────────────┐     ┌─────────────────┐       │
    │  │  SELF-HOSTED    │     │    EXTERNAL     │       │
    │  │  (RunPod/GPU)   │     │    (APIs)       │       │
    │  ├─────────────────┤     ├─────────────────┤       │
    │  │ Faster Whisper  │     │ Groq API        │       │
    │  │ Local LLM       │     │ OpenRouter      │       │
    │  │ Tesseract       │     │ OpenAI          │       │
    │  │ Embeddings      │     │ Anthropic       │       │
    │  └─────────────────┘     └─────────────────┘       │
    └────────────────────────────────────────────────────┘

---

Componentes Internos

Componente	Puerto	Función
Clara (secretaría)	5051	Ingesta inmutable
Alfred (producción)	5052	Flujos predefinidos
Mason (administración)	5053	Enriquecimiento
Feldman (contable)	5054	Consolidación

---

Modos de Despliegue

EXTERNAL

grace:
  mode: EXTERNAL
  external:
    providers_allowed: [groq, openrouter, openai, anthropic]

• Todas las llamadas a proveedores externos
• Sin infraestructura propia
• Ideal para: inicio rápido, bajo volumen

SELF_HOSTED

grace:
  mode: SELF_HOSTED
  self_hosted:
    endpoint: "https://your-runpod-endpoint.runpod.net"
    timeout_ms: 30000

• Todas las llamadas a infraestructura propia
• Requiere RunPod/GPU configurado
• Ideal para: privacidad total, alto volumen

SEMI (Recomendado)

grace:
  mode: SEMI
  tier_preference:
    - SELF_HOSTED
    - EXTERNAL
  self_hosted:
    endpoint: "..."
    retry_on_failure: true
  external:
    providers_allowed: [groq, openrouter]

• Intenta self-hosted primero
• Fallback automático a external
• Balance privacidad/disponibilidad

---

Flujo de Request

┌──────────┐     ┌──────────┐     ┌───────────────┐     ┌──────────────┐
│  Cliente │────▶│   MODELO CERO   │────▶│  Deployment   │────▶│   Servicio   │
│          │     │          │     │    Router     │     │   (IA)       │
└──────────┘     └────┬─────┘     └───────┬───────┘     └──────────────┘
                      │                    │
                      │  1. Recibe request │
                      │  2. Lee config/deployment.yaml
                      │  3. Obtiene credenciales de Vaultwarden
                      │  4. Construye S-CONTRACT request
                      │                    │
                      │           ┌────────▼────────┐
                      │           │  mode: SEMI     │
                      │           ├─────────────────┤
                      │           │ 1. Try SELF_HOSTED
                      │           │ 2. If fail → EXTERNAL
                      │           └─────────────────┘

---

Servicios Docker

Servicio	Puerto	Descripción
PostgreSQL	5432	Base de datos principal
Directus	8055	Interface datos
FileBrowser	8081	Gestión archivos
Vaultwarden	8082	Key Vault
Shlink	8083	Acortador URLs
Addy.io	8084	Alias correo
Redis	6379	Cache y colas

---

Conectores de IA

GRACE Connector

• Procesa requests de módulos GRACE
• Soporta todos los M-CONTRACTs
• Maneja fallback chain según M-CONTRACT

PENNY Connector

• Conexión WebSocket para real-time voice
• Sesiones de voz bidireccionales
• Integración con ASR/TTS

FACTORY Connector

• Jobs de generación iterativa
• Gestión de iteraciones y convergencia
• Tracking de costos

---

Gestión de Credenciales

Las credenciales se referencian con URIs kv://:

URI	Contenido
kv://deck/credentials/groq	API key Groq
kv://deck/credentials/openrouter	API key OpenRouter
kv://deck/credentials/runpod	API key RunPod
kv://deck/credentials/grace	Credenciales consolidadas GRACE
kv://deck/credentials/penny	Credenciales PENNY
kv://deck/credentials/factory	Credenciales FACTORY

---

Integración S-CONTRACT

MODELO CERO construye requests siguiendo S-CONTRACT v2.1:

{
  "contract_version": "2.1",
  "profile": "FULL",
  "envelope": {
    "trace_id": "uuid-generado-por-deck",
    "idempotency_key": "sha256-del-contenido"
  },
  "routing": {
    "module": "ASR_ENGINE"
  },
  "deployment": {
    "mode": "SEMI",
    "tier_preference": ["SELF_HOSTED", "EXTERNAL"],
    "credentials_ref": "kv://deck/credentials/grace"
  },
  "payload": {
    "type": "audio",
    "encoding": "url",
    "content": "https://storage.tzzrdeck.me/audio/file.mp3"
  }
}

---

Estructura de Directorios

deck/
├── config/
│   └── deployment.yaml      # Modos de despliegue
├── docker-compose.yml       # Servicios
├── docs/
│   ├── ARQUITECTURA.md
│   └── ESPECIFICACION_SERVIDOR.md
├── .env                     # Variables entorno
└── README.md