tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
1b392803fdc033ed34ee09d466b0eead8599d7a3
system-docs/v4-archive/contratos-comunes/docs/LECCIONES_CORP.md
ARCHITECT 1b392803fd Archive: System v4 - Estado al 2024-12-24
2025-12-24 17:28:34 +00:00

13 KiB
Raw Blame History

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)

{
  "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)

{
  "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

{
  "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

# 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

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

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)

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)

-- 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)

-- 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:

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:

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

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"

Reference in New Issue View Git Blame Copy Permalink