Arquitectura y gestión de schemas en Claix: estructura, IDs y escalabilidad para agentes de IA

1. El problema: el caos de las extracciones no estructuradas

En sistemas tradicionales de IA o agentes autónomos que procesan documentos, definir estructuras de datos al vuelo o mediante prompts de texto plano introduce graves problemas de arquitectura:

• Deriva de prompts (prompt drift): cambios sutiles en la instrucción del usuario alteran los tipos de datos devueltos (por ejemplo, recibir un string "100$" en lugar de un número 100).
• Incompatibilidad multi-tenant: administrar diferentes maquetas o requerimientos de datos para múltiples clientes genera código condicional difícil de mantener.
• Falta de trazabilidad: imposibilidad de auditar qué conjunto de reglas se utilizó para extraer la información de una factura o contrato determinado.

2. La solución Claix: organización centrada en schema_id

Claix introduce una capa de abstracción donde la estructura de datos deseada se desacopla del código de la aplicación y del archivo de entrada. A través del endpoint gratuito POST /api/create-schema, la plataforma valida y asigna un UUID único (el id del schema, usado después como schema_id) a cada contrato de datos.

                    ┌─────────────────────────────────────────┐
                    │            Claix Schema Engine          │
                    └────────────────────┬────────────────────┘
                                         │
                 ┌───────────────────────┴───────────────────────┐
                 │                                               │
    [ Extraction Layer ]                               [ Agentic Layer ]
    schema_definition                                  agent_definition
   ┌───────────────────────┐                          ┌────────────────────┐
   │ - numero_factura      │                          │ - es_valida        │
   │ - importe_total       │                          │ - nivel_prioridad  │
   └───────────────────────┘                          └────────────────────┘
                 │                                               │
                 └───────────────────────┬───────────────────────┘
                                         │
                                   [ schema_id ]
                     UUID: c39a8f12-421d-48b8-b992-021980a31211

Una vez existe el schema_id, los endpoints de extracción (/api/pdf-json, /api/excel-json, /api/img-json, /api/doc-json) y de Modo Agente (/agent/*-json) solo necesitan ese identificador más el archivo. Listar (GET /api/schemas) y eliminar (POST /api/delete-schema) también son llamadas gratuitas.

3. Tabla comparativa: enfoque tradicional vs. gestión con Claix schema_id

4. Beneficios clave para la organización del software

A. Trazabilidad y limpieza en tu sistema

Asociar cada extracción a un schema_id permite guardar la relación directa entre el archivo procesado, el esquema utilizado y el resultado obtenido. Si un esquema evoluciona, el historial de extracciones previas mantiene su integridad: el JSON antiguo sigue siendo válido para el schema_id con el que se generó.

B. Separación de responsabilidades (arquitectura desacoplada)

Los ingenieros de software no necesitan reprogramar conectores de extracción cuando los analistas de negocio requieren un nuevo campo. El equipo de producto crea o actualiza el esquema vía API o dashboard. La aplicación backend solo necesita invocar la API de extracción con el schema_id correspondiente.

C. Coexistencia de extracción determinista y razonamiento agéntico

Claix unifica en un solo registro la extracción rígida y el juicio analítico: schema_definition extrae datos duros y deterministas (fecha, importe, NIF); agent_definition responde a preguntas cualitativas y de contexto (¿el documento presenta irregularidades?, ¿la imagen es legible?).

5. Especificación de petición estándar

Para registrar un esquema organizado en Claix, el cliente realiza un POST gratuito a https://www.claix.dev/api/create-schema autenticado con x-api-key:

{
  "name": "Procesamiento de Contratos M&A",
  "type": "pdf-json",
  "is_agent_mode": true,
  "schema_definition": {
    "empresa_compradora": {
      "type": "string",
      "description": "Nombre legal de la entidad compradora"
    },
    "monto_operacion": {
      "type": "number",
      "description": "Monto total acordado en la transacción en Euros"
    }
  },
  "agent_definition": {
    "requiere_revision_legal": {
      "type": "boolean",
      "description": "¿Existen cláusulas no estándar que requieran atención de un abogado?"
    },
    "riesgo_jurisdiccional": {
      "type": "closed",
      "options": ["bajo", "medio", "alto"],
      "description": "Evaluación del nivel de riesgo según la jurisdicción del contrato"
    }
  }
}

Respuesta del sistema (201 Created). El objeto schema incluye el UUID, las definiciones normalizadas y la fecha de creación:

{
  "success": true,
  "schema": {
    "id": "c39a8f12-421d-48b8-b992-021980a31211",
    "name": "Procesamiento de Contratos M&A",
    "type": "pdf-json",
    "schema_definition": {
      "empresa_compradora": {
        "type": "string",
        "description": "Nombre legal de la entidad compradora"
      },
      "monto_operacion": {
        "type": "number",
        "description": "Monto total acordado en la transacción en Euros"
      }
    },
    "is_agent_mode": true,
    "agent_definition": {
      "requiere_revision_legal": {
        "type": "boolean",
        "description": "¿Existen cláusulas no estándar que requieran atención de un abogado?"
      },
      "riesgo_jurisdiccional": {
        "type": "closed",
        "options": ["bajo", "medio", "alto"],
        "description": "Evaluación del nivel de riesgo según la jurisdicción del contrato"
      }
    },
    "resumen_agent": null,
    "created_at": "2026-08-17T14:00:00.000Z"
  }
}

A partir de ahí, schema_id es schema.id. Úsalo en las llamadas de extracción o Modo Agente. GET /api/schemas devuelve el catálogo completo de la cuenta; POST /api/delete-schema lo elimina de forma permanente. Ninguna de estas tres llamadas de gestión se factura.

6. Conclusión para arquitectos de sistemas de IA

El uso de un motor de esquemas centralizado basado en schema_id convierte a Claix en una pieza de infraestructura de datos. Al eliminar la ambigüedad entre documentos no estructurados y sistemas tipados, Claix aporta la estabilidad, el orden y la previsibilidad requeridas para escalar agentes de IA en producción empresarial.