system-docs/v4-archive/contratos-comunes/docs/FACTORY_PROTOCOL_v1.0.md

THE FACTORY Protocol v1.0

Protocolo de Generación Iterativa con Director y Auditores

1. Visión General

THE FACTORY es el sistema de generación iterativa del ecosistema TZZR. Implementa un ciclo de mejora continua donde un Director coordina la generación, un Executor produce artefactos, un Evaluator evalúa la calidad, y un Auditor registra todo para trazabilidad.

┌─────────────────────────────────────────────────────────────┐
│                      THE FACTORY                            │
│                                                             │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐             │
│   │ DIRECTOR │───▶│ EXECUTOR │───▶│ EVALUATOR│             │
│   │ (decide) │◀───│(genera)  │◀───│ (evalúa) │             │
│   └────┬─────┘    └──────────┘    └──────────┘             │
│        │                                                    │
│        ▼                                                    │
│   ┌──────────┐                                             │
│   │ AUDITOR  │ ──▶ SENTINEL                                │
│   │(registra)│                                             │
│   └──────────┘                                             │
└─────────────────────────────────────────────────────────────┘

2. Componentes

2.1 DIRECTOR

El Director es el cerebro de THE FACTORY. Sus responsabilidades:

• Recibir jobs de ALFRED (DECK) o CLARA (CORP)
• Seleccionar modelos apropiados para cada tarea
• Decidir convergencia basándose en confianza y mejora marginal
• Gestionar presupuesto y límites de iteraciones
• Coordinar el flujo entre Executor y Evaluator

// Decisión de convergencia
const decision = director.decideConvergence(job, evaluation);
// Converge si:
// - confidence >= 0.85 (umbral configurable)
// - mejora < 0.02 con confidence > 0.7 (rendimientos decrecientes)

2.2 EXECUTOR

El Executor genera artefactos según el tipo de función:

Función	Modelos Disponibles
TEXT_GENERATION	claude-sonnet, claude-opus, gpt-4, llama-3
IMAGE_GENERATION	flux-pro, flux-dev, sdxl, dalle-3
CODE_GENERATION	claude-sonnet, claude-opus, gpt-4
DOCUMENT_GENERATION	claude-opus, gpt-4
AUDIO_GENERATION	elevenlabs, bark, xtts
VIDEO_GENERATION	runway, pika, stable-video

2.3 EVALUATOR

El Evaluator analiza cada artefacto contra el objetivo:

{
  "confidence": 0.82,
  "strengths": ["Cumple estructura básica", "Lenguaje apropiado"],
  "weaknesses": ["Falta detalle en sección X"],
  "feedback": "Mejorar especificidad y añadir ejemplos concretos."
}

2.4 AUDITOR

El Auditor registra cada evento para trazabilidad completa:

• JOB_CREATED - Inicio del job
• JOB_STARTED - Ejecución iniciada
• ITERATION_COMPLETED - Cada iteración
• JOB_COMPLETED - Finalización

3. Estados de Job

PENDING ──▶ QUEUED ──▶ RUNNING ──▶ EVALUATING ──┬──▶ CONVERGED
                         │            │          │
                         │            │          └──▶ EXHAUSTED
                         │            │
                         └────────────┘
                           (iteración)

Estado	Descripción
PENDING	Job creado, esperando recursos
QUEUED	En cola para ejecución
RUNNING	Executor generando artefacto
EVALUATING	Evaluator analizando resultado
CONVERGED	Objetivo alcanzado (confidence >= threshold)
EXHAUSTED	Límite de iteraciones o presupuesto alcanzado
FAILED	Error irrecuperable
CANCELLED	Cancelado por usuario

4. Estructura del Job

4.1 Request (S-CONTRACT compatible)

{
  "seed": "Genera un plan de entrenamiento PPL de 4 semanas...",
  "objective": "Plan estructurado con progresión semanal y ejercicios específicos",
  "function": "TEXT_GENERATION",
  "limits": {
    "max_cycles": 5,
    "budget_usd": 1.0,
    "timeout_ms": 120000
  },
  "input_refs": ["locker://deck/fitness/datos.json"],
  "output_format": "markdown",
  "tags": ["deck", "fitness", "plan"],
  "metadata": {
    "source": "ALFRED",
    "project_id": 123
  }
}

4.2 Response

{
  "job_id": "fac-abc123-xyz789",
  "state": "CONVERGED",
  "total_iterations": 3,
  "total_cost_usd": 0.47,
  "final_artifact_ref": "locker://factory/artifacts/abc123.md",
  "final_confidence": 0.89,
  "convergence_reason": "confidence_threshold_met",
  "iterations": [
    {
      "number": 1,
      "confidence": 0.72,
      "feedback": "Añadir más detalle en ejercicios"
    },
    {
      "number": 2,
      "confidence": 0.81,
      "feedback": "Mejorar progresión de pesos"
    },
    {
      "number": 3,
      "confidence": 0.89,
      "feedback": null
    }
  ]
}

5. Integración con ALFRED y CLARA

5.1 ALFRED (DECK - Lite)

ALFRED usa THE FACTORY para generación de contenido personal:

// alfred.js
const result = await factory.submitJob({
  seed: "Genera plan de entrenamiento para perder peso",
  objective: "Plan PPL estructurado con progresión",
  function: "TEXT_GENERATION",
  tags: ["deck", "fitness"],
  limits: { max_cycles: 4, budget_usd: 0.3 }
});

5.2 CLARA (CORP - Full)

CLARA usa THE FACTORY para documentos certificados:

// clara.js
const result = await factory.submitJob({
  seed: "Genera factura profesional para pedido ORD-2025-001",
  objective: "Factura PDF con todos los datos fiscales",
  function: "DOCUMENT_GENERATION",
  tags: ["corp", "factura"],
  limits: { max_cycles: 3, budget_usd: 0.5 }
});

// CLARA añade certificación con NOTARIO
const certified = await notario.certify(result);

6. Flujo de Iteración

                    ┌─────────────────────────────────────┐
                    │         ITERACIÓN N                 │
                    └─────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────┐
│  1. DIRECTOR prepara seed + feedback de iteración N-1      │
└─────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────┐
│  2. EXECUTOR genera artefacto con modelo seleccionado      │
│     - Calcula hash del artefacto                           │
│     - Guarda en LOCKER                                     │
└─────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────┐
│  3. EVALUATOR evalúa artefacto vs objetivo                 │
│     - confidence: 0.0 - 1.0                                │
│     - strengths: []                                        │
│     - weaknesses: []                                       │
│     - feedback: "..."                                      │
└─────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────┐
│  4. AUDITOR registra iteración en SENTINEL                 │
└─────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────┐
│  5. DIRECTOR decide:                                        │
│     - confidence >= 0.85 → CONVERGED                       │
│     - cost >= budget → EXHAUSTED                           │
│     - iteration >= max → EXHAUSTED                         │
│     - else → ITERAR (volver a paso 1)                      │
└─────────────────────────────────────────────────────────────┘

7. Costes y Límites

7.1 Costes por Modelo (estimados)

Modelo	Coste por 1K tokens
claude-sonnet	$0.003
claude-opus	$0.015
gpt-4	$0.01
flux-pro	$0.05/imagen
flux-dev	$0.02/imagen

7.2 Límites por Defecto

const DEFAULT_LIMITS = {
  max_cycles: 5,           // Máximo de iteraciones
  budget_usd: 1.0,         // Presupuesto máximo
  timeout_ms: 120000,      // 2 minutos por iteración
  convergence_threshold: 0.85  // Umbral de convergencia
};

8. Despliegue en RUNPOD

THE FACTORY se despliega como un Serverless Endpoint en RUNPOD:

# runpod-deployment.yaml
endpoint:
  name: the-factory
  gpu: RTX-A4000  # Para generación de imágenes
  workers:
    min: 0
    max: 3
  timeout: 300
  env:
    - ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    - LOCKER_API_KEY: ${LOCKER_API_KEY}
    - SENTINEL_URL: https://sentinel.tzzr.net

9. API Reference

POST /jobs

Crear nuevo job de generación.

Request:

{
  "seed": "string",
  "objective": "string",
  "function": "TEXT_GENERATION | IMAGE_GENERATION | ...",
  "limits": { "max_cycles": 5, "budget_usd": 1.0 },
  "tags": ["string"]
}

Response:

{
  "job_id": "string",
  "state": "PENDING"
}

GET /jobs/{job_id}

Obtener estado de job.

Response:

{
  "job_id": "string",
  "state": "RUNNING | CONVERGED | ...",
  "current_iteration": 2,
  "total_cost_usd": 0.15
}

GET /jobs/{job_id}/result

Obtener resultado completo.

Response: Job completo con todas las iteraciones.

DELETE /jobs/{job_id}

Cancelar job en ejecución.

10. Changelog

v1.0 (2025-01-10)

• Versión inicial del protocolo
• Componentes: Director, Executor, Evaluator, Auditor
• Integración con ALFRED y CLARA
• Soporte para TEXT, IMAGE, CODE, DOCUMENT generation

---

Este documento es parte del sistema S-CONTRACT v2.1