trustgraph/docs/tech-specs/jsonl-prompt-output.es.md

---
layout: default
title: "Especificación técnica de la salida de JSONL para prompts"
parent: "Spanish (Beta)"
---

# Especificación técnica de la salida de JSONL para prompts

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## Resumen

Esta especificación describe la implementación del formato de salida JSONL (JSON Lines)
para respuestas de prompts en TrustGraph. JSONL permite la extracción resistente a
la truncación de datos estructurados de las respuestas de los LLM, abordando problemas
críticos con las salidas de matrices JSON que se corrompen cuando las respuestas de
los LLM alcanzan los límites de tokens de salida.

Esta implementación admite los siguientes casos de uso:

1. **Extracción resistente a la truncación**: Extraer resultados parciales válidos
   incluso cuando la salida del LLM se trunca a la mitad de la respuesta.
2. **Extracción a gran escala**: Manejar la extracción de muchos elementos sin riesgo
   de fallo completo debido a los límites de tokens.
3. **Extracción de tipos mixtos**: Admitir la extracción de múltiples tipos de
   entidades (definiciones, relaciones, entidades, atributos) en un solo prompt.
4. **Salida compatible con el streaming**: Permitir el procesamiento futuro de
   resultados de extracción de forma incremental.

## Objetivos

**Compatibilidad con versiones anteriores**: Las indicaciones existentes que utilizan `response-type: "text"` y
  `response-type: "json"` siguen funcionando sin modificaciones.
<<<<<<< HEAD
**Resiliencia a la truncación**: Las salidas parciales del LLM producen resultados válidos parciales
=======
**Resiliencia ante la truncación**: Las salidas parciales del LLM producen resultados válidos parciales
>>>>>>> 82edf2d (New md files from RunPod)
  en lugar de un fallo completo.
**Validación de esquema**: Soporte para la validación de esquemas JSON para objetos individuales.
**Uniones discriminadas**: Soporte para salidas de tipos mixtos utilizando un campo `type`
  discriminador.
**Cambios mínimos en la API**: Extiende la configuración de indicaciones existente con un nuevo
  tipo de respuesta y clave de esquema.

<<<<<<< HEAD
## Contexto
=======
## Antecedentes
>>>>>>> 82edf2d (New md files from RunPod)

### Arquitectura actual

El servicio de indicaciones admite dos tipos de respuesta:

1. `response-type: "text"`: Respuesta de texto sin formato devuelta tal cual.
2. `response-type: "json"`: JSON analizado de la respuesta, validado contra
   un esquema `schema` opcional.

Implementación actual en `trustgraph-flow/trustgraph/template/prompt_manager.py`:

```python
class Prompt:
    def __init__(self, template, response_type = "text", terms=None, schema=None):
        self.template = template
        self.response_type = response_type
        self.terms = terms
        self.schema = schema
```

### Limitaciones actuales

Cuando las indicaciones de extracción solicitan una salida en formato de matrices JSON (`[{...}, {...}, ...]`):

**Corrupción por truncamiento**: Si el LLM alcanza los límites de tokens de salida a la mitad de la matriz,
  toda la respuesta se vuelve JSON inválido y no se puede analizar.
**Análisis todo o nada**: Debe recibir la salida completa antes de analizarla.
**Sin resultados parciales**: Una respuesta truncada produce cero datos utilizables.
**No es fiable para extracciones grandes**: Cuantos más elementos se extraen, mayor es el riesgo de fallo.

<<<<<<< HEAD
Esta especificación aborda estas limitaciones introduciendo el formato JSONL para
=======
Esta especificación aborda estas limitaciones mediante la introducción del formato JSONL para
>>>>>>> 82edf2d (New md files from RunPod)
las indicaciones de extracción, donde cada elemento extraído es un objeto JSON completo en su
propia línea.

## Diseño técnico

### Extensión del tipo de respuesta

Agregue un nuevo tipo de respuesta `"jsonl"` junto con los tipos existentes `"text"` y `"json"`.

#### Cambios de configuración

**Nuevo valor del tipo de respuesta:**

```
"response-type": "jsonl"
```

**Interpretación del esquema:**

La clave existente `"schema"` se utiliza tanto para el tipo de respuesta `"json"` como para el tipo de respuesta `"jsonl"`.
La interpretación depende del tipo de respuesta:

`"json"`: El esquema describe toda la respuesta (típicamente un array u objeto).
`"jsonl"`: El esquema describe cada línea/objeto individual.

```json
{
  "response-type": "jsonl",
  "schema": {
    "type": "object",
    "properties": {
      "entity": { "type": "string" },
      "definition": { "type": "string" }
    },
    "required": ["entity", "definition"]
  }
}
```

Esto evita cambios en las herramientas de configuración y los editores.

### Especificación del formato JSONL

#### Extracción simple

<<<<<<< HEAD
Para los prompts que extraen un solo tipo de objeto (definiciones, relaciones,
temas, filas), la salida es un objeto JSON por línea sin envoltorio:

**Formato de salida del prompt:**
=======
Para las indicaciones que extraen un solo tipo de objeto (definiciones, relaciones,
temas, filas), la salida es un objeto JSON por línea sin envoltorio:

**Formato de salida de la indicación:**
>>>>>>> 82edf2d (New md files from RunPod)
```
{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"}
{"entity": "chlorophyll", "definition": "Green pigment in plants"}
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}
```

**Contraste con el formato anterior de matriz JSON:**
```json
[
  {"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"},
  {"entity": "chlorophyll", "definition": "Green pigment in plants"},
  {"entity": "mitochondria", "definition": "Powerhouse of the cell"}
]
```

Si el modelo de lenguaje (LLM) trunca después de la línea 2, el formato de matriz JSON produce JSON inválido,
mientras que JSONL produce dos objetos válidos.

#### Extracción de Tipos Mixtos (Uniones Discriminadas)

<<<<<<< HEAD
Para las indicaciones que extraen múltiples tipos de objetos (por ejemplo, tanto definiciones como
=======
Para indicaciones que extraen múltiples tipos de objetos (por ejemplo, tanto definiciones como
>>>>>>> 82edf2d (New md files from RunPod)
relaciones, o entidades, relaciones y atributos), utilice un campo `"type"`
como discriminador:

**Formato de salida de la indicación:**
```
{"type": "definition", "entity": "DNA", "definition": "Molecule carrying genetic instructions"}
{"type": "relationship", "subject": "DNA", "predicate": "located_in", "object": "cell nucleus", "object-entity": true}
{"type": "definition", "entity": "RNA", "definition": "Molecule that carries genetic information"}
{"type": "relationship", "subject": "RNA", "predicate": "transcribed_from", "object": "DNA", "object-entity": true}
```

**Esquema para uniones discriminadas utiliza `oneOf`:**
```json
{
  "response-type": "jsonl",
  "schema": {
    "oneOf": [
      {
        "type": "object",
        "properties": {
          "type": { "const": "definition" },
          "entity": { "type": "string" },
          "definition": { "type": "string" }
        },
        "required": ["type", "entity", "definition"]
      },
      {
        "type": "object",
        "properties": {
          "type": { "const": "relationship" },
          "subject": { "type": "string" },
          "predicate": { "type": "string" },
          "object": { "type": "string" },
          "object-entity": { "type": "boolean" }
        },
        "required": ["type", "subject", "predicate", "object", "object-entity"]
      }
    ]
  }
}
```

#### Extracción de Ontología

Para la extracción basada en ontologías con entidades, relaciones y atributos:

**Formato de salida del prompt:**
```
{"type": "entity", "entity": "Cornish pasty", "entity_type": "fo/Recipe"}
{"type": "entity", "entity": "beef", "entity_type": "fo/Food"}
{"type": "relationship", "subject": "Cornish pasty", "subject_type": "fo/Recipe", "relation": "fo/has_ingredient", "object": "beef", "object_type": "fo/Food"}
{"type": "attribute", "entity": "Cornish pasty", "entity_type": "fo/Recipe", "attribute": "fo/serves", "value": "4 people"}
```

### Detalles de implementación

#### Clase Prompt

La clase `Prompt` existente no requiere cambios. El campo `schema` se reutiliza
para JSONL, y su interpretación está determinada por `response_type`:

```python
class Prompt:
    def __init__(self, template, response_type="text", terms=None, schema=None):
        self.template = template
        self.response_type = response_type
        self.terms = terms
        self.schema = schema  # Interpretation depends on response_type
```

#### PromptManager.load_config

No se requieren cambios: la carga de configuración existente ya gestiona la
clave `schema`.

#### Análisis de JSONL

Agregar un nuevo método de análisis para respuestas JSONL:

```python
def parse_jsonl(self, text):
    """
    Parse JSONL response, returning list of valid objects.

    Invalid lines (malformed JSON, empty lines) are skipped with warnings.
    This provides truncation resilience - partial output yields partial results.
    """
    results = []

    for line_num, line in enumerate(text.strip().split('\n'), 1):
        line = line.strip()

        # Skip empty lines
        if not line:
            continue

        # Skip markdown code fence markers if present
        if line.startswith('```'):
            continue

        try:
            obj = json.loads(line)
            results.append(obj)
        except json.JSONDecodeError as e:
            # Log warning but continue - this provides truncation resilience
            logger.warning(f"JSONL parse error on line {line_num}: {e}")

    return results
```

#### Cambios en PromptManager.invoke

Extender el método invoke para manejar el nuevo tipo de respuesta:

```python
async def invoke(self, id, input, llm):
    logger.debug("Invoking prompt template...")

    terms = self.terms | self.prompts[id].terms | input
    resp_type = self.prompts[id].response_type

    prompt = {
        "system": self.system_template.render(terms),
        "prompt": self.render(id, input)
    }

    resp = await llm(**prompt)

    if resp_type == "text":
        return resp

    if resp_type == "json":
        try:
            obj = self.parse_json(resp)
        except:
            logger.error(f"JSON parse failed: {resp}")
            raise RuntimeError("JSON parse fail")

        if self.prompts[id].schema:
            try:
                validate(instance=obj, schema=self.prompts[id].schema)
                logger.debug("Schema validation successful")
            except Exception as e:
                raise RuntimeError(f"Schema validation fail: {e}")

        return obj

    if resp_type == "jsonl":
        objects = self.parse_jsonl(resp)

        if not objects:
            logger.warning("JSONL parse returned no valid objects")
            return []

        # Validate each object against schema if provided
        if self.prompts[id].schema:
            validated = []
            for i, obj in enumerate(objects):
                try:
                    validate(instance=obj, schema=self.prompts[id].schema)
                    validated.append(obj)
                except Exception as e:
                    logger.warning(f"Object {i} failed schema validation: {e}")
            return validated

        return objects

    raise RuntimeError(f"Response type {resp_type} not known")
```

### Prompts Afectados

Los siguientes prompts deben migrarse al formato JSONL:

| ID del Prompt | Descripción | Campo de Tipo |
|-----------|-------------|------------|
| `extract-definitions` | Extracción de entidades/definiciones | No (un solo tipo) |
| `extract-relationships` | Extracción de relaciones | No (un solo tipo) |
| `extract-topics` | Extracción de temas/definiciones | No (un solo tipo) |
| `extract-rows` | Extracción de filas estructuradas | No (un solo tipo) |
| `agent-kg-extract` | Extracción combinada de definiciones + relaciones | Sí: `"definition"`, `"relationship"` |
| `extract-with-ontologies` / `ontology-extract` | Extracción basada en ontología | Sí: `"entity"`, `"relationship"`, `"attribute"` |

### Cambios en la API

#### Perspectiva del Cliente

El análisis JSONL es transparente para los clientes de la API del servicio de prompts. El análisis se
realiza en el servidor en el servicio de prompts, y la respuesta se devuelve a través del
campo estándar `PromptResponse.object` como una matriz JSON serializada.

Cuando los clientes llaman al servicio de prompts (a través de `PromptClient.prompt()` o similar):

**`response-type: "json"`** con esquema de matriz → el cliente recibe Python `list`
**`response-type: "jsonl"`** → el cliente recibe Python `list`

Desde la perspectiva del cliente, ambos devuelven estructuras de datos idénticas. La
<<<<<<< HEAD
diferencia es completamente en cómo se analiza la salida del LLM en el servidor:

Formato de matriz JSON: Una sola llamada a `json.loads()`; falla completamente si se trunca
Formato JSONL: Análisis línea por línea; produce resultados parciales si se trunca

Esto significa que el código de cliente existente que espera una lista de los prompts de extracción
no requiere cambios al migrar los prompts de JSON a JSONL.
=======
diferencia radica completamente en cómo se analiza la salida del LLM en el servidor:

Formato de matriz JSON: Una sola llamada a `json.loads()`; falla por completo si se trunca
Formato JSONL: Análisis línea por línea; produce resultados parciales si se trunca

Esto significa que el código de cliente existente que espera una lista de los prompts de extracción
no requiere cambios al migrar los prompts del formato JSON al formato JSONL.
>>>>>>> 82edf2d (New md files from RunPod)

#### Valor de Retorno del Servidor

Para `response-type: "jsonl"`, el método `PromptManager.invoke()` devuelve un
`list[dict]` que contiene todos los objetos analizados y validados correctamente. Esta
lista se serializa luego a JSON para el campo `PromptResponse.object`.

#### Manejo de Errores

Resultados vacíos: Devuelve una lista vacía `[]` con un registro de advertencia
Fallo parcial de análisis: Devuelve una lista de objetos analizados correctamente con
  registros de advertencia para los fallos
Fallo completo de análisis: Devuelve una lista vacía `[]` con registros de advertencia

<<<<<<< HEAD
Esto difiere de `response-type: "json"` que lanza `RuntimeError` en
=======
Esto difiere de `response-type: "json"`, que lanza `RuntimeError` en
>>>>>>> 82edf2d (New md files from RunPod)
caso de fallo de análisis. El comportamiento permisivo para JSONL es intencional para proporcionar
resistencia a la truncación.

### Ejemplo de Configuración

Ejemplo completo de configuración de prompt:

```json
{
  "prompt": "Extract all entities and their definitions from the following text. Output one JSON object per line.\n\nText:\n{{text}}\n\nOutput format per line:\n{\"entity\": \"<name>\", \"definition\": \"<definition>\"}",
  "response-type": "jsonl",
  "schema": {
    "type": "object",
    "properties": {
      "entity": {
        "type": "string",
        "description": "The entity name"
      },
      "definition": {
        "type": "string",
        "description": "A clear definition of the entity"
      }
    },
    "required": ["entity", "definition"]
  }
}
```

## Consideraciones de seguridad

**Validación de entrada**: El análisis JSON utiliza `json.loads()` estándar, que es seguro
  contra ataques de inyección.
**Validación de esquema**: Utiliza `jsonschema.validate()` para la aplicación de esquemas.
**Sin nueva superficie de ataque**: El análisis de JSONL es estrictamente más seguro que el análisis de matrices JSON
  debido al procesamiento línea por línea.

## Consideraciones de rendimiento

**Memoria**: El análisis línea por línea utiliza menos memoria máxima que la carga de matrices JSON completas.
<<<<<<< HEAD
  
**Latencia**: El rendimiento del análisis es comparable al análisis de matrices JSON.
**Validación**: La validación de esquema se ejecuta por objeto, lo que añade sobrecarga, pero
  permite resultados parciales en caso de fallo de la validación.

## Estrategia de pruebas

=======
  **Latencia**: El rendimiento del análisis es comparable al análisis de matrices JSON.
**Validación**: La validación de esquemas se ejecuta por objeto, lo que añade sobrecarga, pero
permite resultados parciales en caso de fallo de la validación.
  
## Estrategia de pruebas


>>>>>>> 82edf2d (New md files from RunPod)
### Pruebas Unitarias

Análisis de JSONL con entrada válida
Análisis de JSONL con líneas vacías
Análisis de JSONL con bloques de código Markdown
<<<<<<< HEAD
Análisis de JSONL con línea final truncada
Análisis de JSONL con líneas JSON inválidas intercaladas
Validación de esquema con uniones discriminadas `oneOf`
Compatibilidad hacia atrás: las indicaciones existentes `"text"` y `"json"` no se modifican
=======
Análisis de JSONL con líneas finales truncadas
Análisis de JSONL con líneas JSON inválidas intercaladas
Validación de esquema con uniones discriminadas `oneOf`
Compatibilidad con versiones anteriores: las indicaciones `"text"` y `"json"` existentes no se modifican
>>>>>>> 82edf2d (New md files from RunPod)

### Pruebas de Integración

Extracción de extremo a extremo con indicaciones JSONL
Extracción con truncamiento simulado (respuesta artificialmente limitada)
Extracción de tipos mixtos con discriminador de tipo
Extracción de ontología con los tres tipos

### Pruebas de Calidad de Extracción

Comparar los resultados de la extracción: formato JSONL frente a formato de matriz JSON.
Verificar la resistencia a la truncación: JSONL produce resultados parciales donde JSON falla.

## Plan de Migración

### Fase 1: Implementación

1. Implementar el método `parse_jsonl()` en `PromptManager`.
2. Extender `invoke()` para manejar `response-type: "jsonl"`.
3. Agregar pruebas unitarias.

### Fase 2: Migración de Prompts

1. Actualizar el prompt y la configuración de `extract-definitions`.
2. Actualizar el prompt y la configuración de `extract-relationships`.
3. Actualizar el prompt y la configuración de `extract-topics`.
4. Actualizar el prompt y la configuración de `extract-rows`.
5. Actualizar el prompt y la configuración de `agent-kg-extract`.
6. Actualizar el prompt y la configuración de `extract-with-ontologies`.

### Fase 3: Actualizaciones Posteriores

1. Actualizar cualquier código que consuma los resultados de la extracción para manejar el tipo de retorno de lista.
2. Actualizar el código que categoriza las extracciones de tipos mixtos según el campo `type`.
3. Actualizar las pruebas que afirman sobre el formato de salida de la extracción.

## Preguntas Abiertas

Ninguna por el momento.

## Referencias

<<<<<<< HEAD
Implementación actual: `trustgraph-flow/trustgraph/template/prompt_manager.py`.
Especificación de JSON Lines: https://jsonlines.org/.
Esquema JSON `oneOf`: https://json-schema.org/understanding-json-schema/reference/combining.html#oneof.
Especificación relacionada: Streaming LLM Responses (`docs/tech-specs/streaming-llm-responses.md`).
=======
Implementación actual: `trustgraph-flow/trustgraph/template/prompt_manager.py`
Especificación de JSON Lines: https://jsonlines.org/
Esquema JSON `oneOf`: https://json-schema.org/understanding-json-schema/reference/combining.html#oneof
Especificación relacionada: Streaming LLM Responses (`docs/tech-specs/streaming-llm-responses.md`)
>>>>>>> 82edf2d (New md files from RunPod)