529 lines
13 KiB
Markdown
529 lines
13 KiB
Markdown
# 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"*
|