338 lines
12 KiB
Markdown
338 lines
12 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
// 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:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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)
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
// 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:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
// 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
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
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:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# 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:**
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"seed": "string",
|
||
|
|
"objective": "string",
|
||
|
|
"function": "TEXT_GENERATION | IMAGE_GENERATION | ...",
|
||
|
|
"limits": { "max_cycles": 5, "budget_usd": 1.0 },
|
||
|
|
"tags": ["string"]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**Response:**
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"job_id": "string",
|
||
|
|
"state": "PENDING"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### GET /jobs/{job_id}
|
||
|
|
|
||
|
|
Obtener estado de job.
|
||
|
|
|
||
|
|
**Response:**
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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*
|