system-docs/v4-archive/contratos-comunes/docs/LECCIONES_CORP.md

# Lecciones para CORP

**Documento de onboarding para empresas del ecosistema TZZR**

---

## Leccion 1: Que es CORP

CORP es una **empresa** dentro del ecosistema TZZR. No es un sistema, es un tenant.

```
ECOSISTEMA TZZR
├── DECK          → Orquestador para HUMANOS
├── CORP          → Orquestador para EMPRESAS (tu)
├── GRACE         → Procesamiento IA
├── THE FACTORY   → Procesamiento documental
├── PENNY         → Asistente de voz (solo humanos)
└── HST           → Sistema de etiquetas
```

### Lo que puedes hacer
- Llamar a GRACE (clasificar, extraer, resumir)
- Llamar a THE FACTORY (procesar documentos)
- Usar etiquetas HST para organizar

### Lo que NO puedes hacer
- Llamar a PENNY (es solo para humanos via DECK)

---

## Leccion 2: S-CONTRACT

Toda comunicacion con GRACE y THE FACTORY usa el formato **S-CONTRACT v2.1**.

### Request minimo (perfil LITE)

```json
{
  "contract_version": "2.1",
  "profile": "LITE",
  "envelope": {
    "trace_id": "uuid-unico-por-request",
    "idempotency_key": "sha256-del-contenido-64-chars"
  },
  "routing": {
    "module": "CLASSIFIER"
  },
  "context": {
    "lang": "es"
  },
  "payload": {
    "type": "text",
    "encoding": "utf-8",
    "content": "Factura de Telefonica por 45.99 EUR"
  }
}
```

### Request completo (perfil FULL)

```json
{
  "contract_version": "2.1",
  "profile": "FULL",
  "envelope": {
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234",
    "step_id": "660e8400-e29b-41d4-a716-446655440001",
    "step_index": 1,
    "timestamp_init": "2025-12-18T10:00:00Z",
    "ttl_ms": 30000
  },
  "routing": {
    "module": "CLASSIFIER",
    "version": "1.0",
    "provider_preference": ["groq", "openai"],
    "max_fallback_level": 2
  },
  "context": {
    "lang": "es",
    "mode": "strict",
    "pii_filter": false,
    "system_instruction": "Clasifica el documento segun categoria contable.",
    "datasets": [
      {
        "codigo": "DS_CATEGORIAS_CORP",
        "tipo": "vocabulary",
        "contenido": "GASTO_OPERATIVO, GASTO_FINANCIERO, INGRESO_VENTA..."
      }
    ],
    "tags": {
      "hst": ["335350bb41a329c..."],
      "hsu": [],
      "emp": ["h_maestro_de_corp..."],
      "pjt": ["h_maestro_proyecto..."]
    },
    "ambiente": {
      "timezone": "Europe/Madrid",
      "locale": "es-ES",
      "currency": "EUR",
      "session_type": "batch"
    }
  },
  "payload": {
    "type": "document",
    "encoding": "url",
    "content": "https://storage.corp.example/factura-001.pdf"
  },
  "deployment": {
    "mode": "SEMI",
    "tier_preference": ["SELF_HOSTED", "EXTERNAL"]
  }
}
```

### Response esperada

```json
{
  "contract_version": "2.1",
  "profile": "FULL",
  "envelope": {
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "a1b2c3d4e5f6...",
    "timestamp_end": "2025-12-18T10:00:03Z"
  },
  "status": {
    "code": "SUCCESS",
    "provider_used": "groq",
    "deployment_used": {
      "mode": "SEMI",
      "tier_used": "EXTERNAL",
      "provider_used": "groq"
    }
  },
  "result": {
    "schema": "classifier_output_v1",
    "data": {
      "category": "GASTO_OPERATIVO",
      "subcategory": "TELECOMUNICACIONES",
      "confidence": 0.94
    }
  },
  "quality": {
    "confidence": 0.94,
    "coverage": 1.0
  },
  "metadata": {
    "model_id": "llama-3.3-70b",
    "processing_ms": 1234
  },
  "errors": []
}
```

### Status codes

| Code | Significado |
|------|-------------|
| `SUCCESS` | Todo bien |
| `PARTIAL` | Resultado incompleto pero usable |
| `ERROR` | Fallo |
| `TIMEOUT` | Excedio tiempo |
| `FALLBACK` | Exito con proveedor alternativo |

---

## Leccion 3: HST (Sistema de Etiquetas)

HST es el sistema de etiquetas que da coherencia semantica a todo.

### API disponible

```bash
# Todas las etiquetas
GET https://tzrtech.org/api/index.json

# Tag especifico
GET https://tzrtech.org/api/tags/{h_maestro}

# Buscar
GET https://tzrtech.org/api/tags?grupo=hst
GET https://tzrtech.org/api/tags?q=finanzas
```

### Grupos de etiquetas

| Grupo | Descripcion | Quien las crea |
|-------|-------------|----------------|
| `hst` | Sistema | tzrtech.org (sync) |
| `emp` | Empresa | Tu (CORP) |
| `hsu` | Usuario | Tu (para tus usuarios) |
| `pjt` | Proyecto | Tu (para tus proyectos) |

### Sistema dual de hashes

```
h_maestro = SHA256(grupo || ':' || ref)
    → Identifica semanticamente (para S-CONTRACT)
    → Ejemplo: SHA256("hst:finanzas") = "a7b3c9..."

mrf = SHA256(bytes_imagen)
    → Identifica el archivo de imagen
    → URL: https://tzrtech.org/{mrf}.png
```

### Calcular h_maestro

```python
import hashlib

def h_maestro(grupo: str, ref: str) -> str:
    return hashlib.sha256(f"{grupo}:{ref}".encode()).hexdigest()

# Ejemplo
h = h_maestro("emp", "corp")  # Tu identidad como empresa
```

---

## Leccion 4: Modulos disponibles

### GRACE (18 modulos)

| Modulo | Familia | Uso |
|--------|---------|-----|
| `CLASSIFIER` | SEMANTICA | Clasificar documentos |
| `SUMMARIZER` | SEMANTICA | Resumir textos |
| `TASK_EXTRACTOR` | SEMANTICA | Extraer tareas de texto |
| `FIELD_EXTRACTOR` | UTILIDADES | Extraer campos estructurados |
| `OCR_CORE` | VISION | Extraer texto de imagenes |
| `ASR_ENGINE` | VOZ | Transcribir audio |
| `EMBEDDINGS` | SEMANTICA | Vectorizar texto |
| `SIMILARITY` | SEMANTICA | Comparar textos |
| `LANG_DETECT` | UTILIDADES | Detectar idioma |

### THE FACTORY

Procesamiento documental:
- PDF a texto
- Extraccion estructurada
- OCR de facturas
- Consolidacion de documentos

---

## Leccion 5: Tablas PostgreSQL

Usaras las mismas estructuras que DECK. Schemas en `contratos-comunes/db-schemas/`.

### Orden de aplicacion

```bash
psql -f 00_types.sql      # Tipos enumerados
psql -f 01_hst_tags.sql   # Etiquetas HST
psql -f 02_task_manager.sql  # Proyectos y tareas
psql -f 03_work_log.sql   # Log de archivos
psql -f 04_ai_context.sql # Contextos IA
psql -f 05_ai_requests.sql # Log de requests
```

### Tabla: hst_tags (tus etiquetas propias)

```sql
CREATE TABLE hst_tags (
    id SERIAL PRIMARY KEY,
    h_maestro VARCHAR(64) UNIQUE NOT NULL,  -- SHA256(grupo:ref)
    ref VARCHAR(50) NOT NULL,               -- Codigo corto
    mrf VARCHAR(64),                        -- Hash de imagen (opcional)
    nombre VARCHAR(100) NOT NULL,
    nombre_en VARCHAR(100),
    grupo hst_grupo NOT NULL,               -- emp, hsu, pjt
    padre_h_maestro VARCHAR(64),            -- Jerarquia
    activo BOOLEAN DEFAULT true
);

-- Tus etiquetas de empresa
INSERT INTO hst_tags (h_maestro, ref, nombre, grupo) VALUES
(generate_h_maestro('emp', 'corp'), 'corp', 'CORP', 'emp');

-- Tus proyectos
INSERT INTO hst_tags (h_maestro, ref, nombre, grupo) VALUES
(generate_h_maestro('pjt', 'contabilidad_2025'), 'contabilidad_2025', 'Contabilidad 2025', 'pjt');
```

### Tabla: s_contract_contexts (contextos reutilizables)

```sql
-- Crear un contexto para tus operaciones
INSERT INTO s_contract_contexts (codigo, nombre, context, deployment) VALUES
(
    'CTX_CORP_FACTURAS',
    'Contexto para facturas CORP',
    '{
        "lang": "es",
        "mode": "strict",
        "system_instruction": "Procesa facturas de CORP. Extrae: proveedor, fecha, importe, IVA.",
        "datasets": [],
        "tags": {"hst": [], "hsu": [], "emp": ["h_corp..."], "pjt": []},
        "ambiente": {"timezone": "Europe/Madrid", "locale": "es-ES", "currency": "EUR"}
    }'::jsonb,
    '{"mode": "SEMI", "tier_preference": ["EXTERNAL", "SELF_HOSTED"]}'::jsonb
);
```

### Tabla: ai_requests (log de tus requests)

```sql
-- Registrar cada request que hagas
INSERT INTO ai_requests (
    trace_id, service, module, context_codigo, status
) VALUES (
    'tu-trace-id',
    'grace',
    'CLASSIFIER',
    'CTX_CORP_FACTURAS',
    'pending'
);

-- Actualizar cuando termine
UPDATE ai_requests SET
    status = 'success',
    tier_used = 'EXTERNAL',
    provider_used = 'groq',
    latency_ms = 1234,
    completed_at = NOW()
WHERE trace_id = 'tu-trace-id';
```

---

## Leccion 6: Tu libro diario (MST + BCK)

Como empresa, llevas un libro diario con dos partes:

### MST (Master)

Registro principal de operaciones:

```sql
CREATE TABLE corp_libro_mst (
    id SERIAL PRIMARY KEY,
    fecha DATE NOT NULL,
    tipo VARCHAR(50) NOT NULL,      -- ingreso, gasto, asiento
    concepto TEXT NOT NULL,
    importe DECIMAL(12,2),
    moneda VARCHAR(3) DEFAULT 'EUR',

    -- Referencias
    documento_ref TEXT,              -- URL al documento
    h_maestro_categoria VARCHAR(64), -- Etiqueta HST

    -- Trazabilidad
    trace_id VARCHAR(36),            -- Si vino de IA
    procesado_por VARCHAR(50),       -- grace, factory, manual

    created_at TIMESTAMP DEFAULT NOW()
);
```

### BCK (Backup/Auditoria)

Copia de respaldo con historial:

```sql
CREATE TABLE corp_libro_bck (
    id SERIAL PRIMARY KEY,
    mst_id INTEGER REFERENCES corp_libro_mst(id),
    version INTEGER DEFAULT 1,
    datos_anteriores JSONB,
    datos_nuevos JSONB,
    motivo_cambio TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);
```

---

## Leccion 7: Flujo de trabajo

```
1. Llega documento (factura PDF)
         │
         ▼
2. Almacenas en bandeja de entrada
         │
         ▼
3. Construyes S-CONTRACT
   {routing: {module: "FIELD_EXTRACTOR"}, ...}
         │
         ▼
4. Envias a GRACE o THE FACTORY
         │
         ▼
5. Recibes respuesta estructurada
   {result: {data: {proveedor: "X", importe: 100}}}
         │
         ▼
6. Registras en tu libro MST
         │
         ▼
7. Etiquetas con HST
         │
         ▼
8. Mueves de bandeja a procesado
```

---

## Leccion 8: Codigo Python base

```python
import hashlib
import uuid
import requests
from datetime import datetime, timezone

class CorpClient:
    def __init__(self, grace_url: str, factory_url: str):
        self.grace_url = grace_url
        self.factory_url = factory_url
        self.emp_h_maestro = self.h_maestro("emp", "corp")

    def h_maestro(self, grupo: str, ref: str) -> str:
        return hashlib.sha256(f"{grupo}:{ref}".encode()).hexdigest()

    def idempotency_key(self, content: str) -> str:
        return hashlib.sha256(content.encode()).hexdigest()

    def build_request(
        self,
        module: str,
        content: str,
        content_type: str = "text",
        system_instruction: str = None,
        tags_pjt: list = None
    ) -> dict:
        return {
            "contract_version": "2.1",
            "profile": "FULL",
            "envelope": {
                "trace_id": str(uuid.uuid4()),
                "idempotency_key": self.idempotency_key(content),
                "timestamp_init": datetime.now(timezone.utc).isoformat()
            },
            "routing": {
                "module": module
            },
            "context": {
                "lang": "es",
                "mode": "strict",
                "system_instruction": system_instruction,
                "tags": {
                    "hst": [],
                    "hsu": [],
                    "emp": [self.emp_h_maestro],
                    "pjt": tags_pjt or []
                },
                "ambiente": {
                    "timezone": "Europe/Madrid",
                    "locale": "es-ES",
                    "currency": "EUR",
                    "session_type": "batch"
                }
            },
            "payload": {
                "type": content_type,
                "encoding": "utf-8" if content_type == "text" else "url",
                "content": content
            },
            "deployment": {
                "mode": "SEMI",
                "tier_preference": ["EXTERNAL", "SELF_HOSTED"]
            }
        }

    def classify(self, text: str) -> dict:
        request = self.build_request(
            module="CLASSIFIER",
            content=text,
            system_instruction="Clasifica el documento: FACTURA, CONTRATO, EMAIL, OTRO"
        )
        response = requests.post(f"{self.grace_url}/process", json=request)
        return response.json()

    def extract_fields(self, document_url: str, fields: list) -> dict:
        request = self.build_request(
            module="FIELD_EXTRACTOR",
            content=document_url,
            content_type="document",
            system_instruction=f"Extrae estos campos: {', '.join(fields)}"
        )
        response = requests.post(f"{self.factory_url}/process", json=request)
        return response.json()


# Uso
client = CorpClient(
    grace_url="https://grace.api.example",
    factory_url="https://factory.api.example"
)

# Clasificar un texto
result = client.classify("Factura de Movistar por 45.99 EUR")
print(result["result"]["data"]["category"])

# Extraer campos de un PDF
result = client.extract_fields(
    "https://storage.corp/factura.pdf",
    ["proveedor", "fecha", "importe", "iva"]
)
print(result["result"]["data"])
```

---

## Resumen

1. **S-CONTRACT** es tu idioma para hablar con GRACE y THE FACTORY
2. **HST** te da etiquetas para organizar todo
3. **h_maestro** identifica cada etiqueta (determinista)
4. **Tu libro MST+BCK** registra tus operaciones
5. **Tu almacenamiento es bandeja de entrada**, no permanente
6. **Habla con DECK** para alinear codigo compartido

---

*Ecosistema TZZR - "Alfred Decide, GRACE Transforma"*