system-docs/03_COMPONENTES/agentes/clara-margaret.md

CLARA y MARGARET - Agentes de Ingesta

Versión: 5.0 Fecha: 2024-12-24

---

Resumen

Aspecto	CLARA	MARGARET
Servidor	DECK (72.62.1.113)	CORP (92.112.181.188)
Puerto	5051	5051
Dominio	Personal	Empresarial
Base de datos	tzzr	corp
Tabla log	clara_log	margaret_log
Bucket R2	deck	corp
Estado	Operativo	Operativo

---

Arquitectura

PACKET (App móvil)
       │
       │ POST /ingest
       │ Content-Type: multipart/form-data
       │ X-Auth-Key: {h_instancia}
       │
       ▼
┌─────────────────────────────────────────┐
│  CLARA (Personal) / MARGARET (Corp)     │
│                                         │
│  1. Validar h_instancia                 │
│  2. Calcular h_entrada (SHA-256)        │
│  3. Subir archivos a R2                 │
│  4. Insertar en log (inmutable)         │
│  5. Estado: 'recibido'                  │
│  6. Responder con h_entrada             │
└─────────────────────────────────────────┘
       │
       ▼
  ALFRED / JARED (siguiente paso)

---

Endpoint de Ingesta

Request

POST /ingest HTTP/1.1
Host: deck.example.com:5051
Content-Type: multipart/form-data
X-Auth-Key: {h_instancia}

--boundary
Content-Disposition: form-data; name="tipo"

documento
--boundary
Content-Disposition: form-data; name="archivo"; filename="doc.pdf"
Content-Type: application/pdf

{binary data}
--boundary--

Response

{
  "success": true,
  "h_entrada": "a1b2c3d4e5f6...",
  "estado": "recibido",
  "timestamp": "2024-12-24T12:00:00Z"
}

---

Cálculo de h_entrada

import hashlib
import json

def calcular_h_entrada(h_instancia, tipo, contenido_bytes, timestamp):
    """
    Calcula el hash único de entrada.

    h_entrada = SHA-256(h_instancia:tipo:sha256(contenido):timestamp)
    """
    hash_contenido = hashlib.sha256(contenido_bytes).hexdigest()

    data = f"{h_instancia}:{tipo}:{hash_contenido}:{timestamp}"

    return hashlib.sha256(data.encode()).hexdigest()

---

Schema: clara_log / margaret_log

CREATE TABLE clara_log (
    id BIGSERIAL PRIMARY KEY,
    h_entrada VARCHAR(64) UNIQUE NOT NULL,
    h_instancia VARCHAR(64) NOT NULL,
    tipo VARCHAR(50) NOT NULL,
    contenido_url TEXT,           -- locker://deck/{h_entrada}/archivo
    contenido_hash VARCHAR(64),   -- SHA-256 del contenido
    metadata JSONB,
    estado VARCHAR(20) DEFAULT 'recibido',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    processed_at TIMESTAMPTZ,
    processed_by VARCHAR(50)      -- 'alfred' o 'manual'
);

-- margaret_log tiene schema idéntico
CREATE TABLE margaret_log (
    id BIGSERIAL PRIMARY KEY,
    h_entrada VARCHAR(64) UNIQUE NOT NULL,
    h_instancia VARCHAR(64) NOT NULL,
    tipo VARCHAR(50) NOT NULL,
    contenido_url TEXT,
    contenido_hash VARCHAR(64),
    metadata JSONB,
    estado VARCHAR(20) DEFAULT 'recibido',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    processed_at TIMESTAMPTZ,
    processed_by VARCHAR(50)
);

---

Estados del Log

Estado	Descripción
recibido	Ingesta completada, pendiente procesamiento
procesando	ALFRED/JARED está procesando
enviado_mason	Enviado a MASON para enriquecimiento
consolidado	Procesado por FELDMAN
error	Error en procesamiento

---

Almacenamiento en R2

Estructura de URLs

locker://deck/{h_entrada}/archivo.ext
locker://corp/{h_entrada}/archivo.ext

Implementación

import boto3

def subir_a_r2(bucket, h_entrada, archivo_bytes, filename):
    """Sube archivo a Cloudflare R2."""

    s3 = boto3.client(
        's3',
        endpoint_url='https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com',
        aws_access_key_id=R2_ACCESS_KEY,
        aws_secret_access_key=R2_SECRET_KEY
    )

    key = f"{h_entrada}/{filename}"

    s3.put_object(
        Bucket=bucket,
        Key=key,
        Body=archivo_bytes
    )

    return f"locker://{bucket}/{key}"

---

Validación de h_instancia

def validar_instancia(h_instancia):
    """
    Valida que h_instancia exista y esté activa.

    TODO: Implementar tabla de instancias activas.
    Actualmente: Validación básica de formato.
    """
    if not h_instancia:
        return False

    if len(h_instancia) != 64:
        return False

    # TODO: Consultar tabla de instancias
    return True

---

Tipos de Ingesta Soportados

Tipo	Descripción	Extensiones
documento	Documentos	pdf, doc, docx
imagen	Imágenes	jpg, png, gif
audio	Audio	mp3, wav, m4a
video	Video	mp4, mov
texto	Texto plano	txt, md
json	Datos estructurados	json

---

Configuración

Variables de Entorno

# CLARA (.env en /opt/clara/)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=tzzr
DB_USER=clara
DB_PASSWORD=****

R2_ENDPOINT=https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
R2_ACCESS_KEY=****
R2_SECRET_KEY=****
R2_BUCKET=deck

# MARGARET (.env en /opt/margaret/)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=corp
DB_USER=margaret
DB_PASSWORD=****

R2_BUCKET=corp

Docker Compose

# CLARA
version: '3.8'
services:
  clara:
    container_name: clara-clara
    image: tzzr/clara:latest
    ports:
      - "5051:5051"
    env_file:
      - .env
    restart: unless-stopped

---

Diferencias CLARA vs MARGARET

Aspecto	CLARA	MARGARET
Uso	Personal	Empresarial
Volumen	Bajo	Alto
Privacidad	Máxima	Compartida (empresa)
Integración	ALFRED	JARED → MASON → FELDMAN
Backup	deck bucket	corp bucket

---

Seguridad

Actual

• Autenticación por h_instancia
• Comunicación HTTP (sin TLS interno)
• .env con permisos 644 (CRÍTICO: cambiar a 600)

Recomendado

• TLS interno con certificados
• Rate limiting
• Validación de tipos MIME
• Escaneo antivirus (ClamAV)

---

Monitoreo

Logs

# CLARA
docker logs clara-clara -f

# MARGARET
docker logs margaret-margaret -f

Métricas Sugeridas

• Ingestas por minuto
• Tamaño promedio de archivos
• Tiempo de procesamiento
• Errores por tipo