Parseurs de Sortie

Parsez et validez les sorties LLM en données structurées avec JSON, schémas Zod, listes et correction automatique.

Pourquoi des Parseurs de Sortie ?

Les LLMs retournent du texte non structuré. Les parseurs de sortie extraient des données structurées, valident les formats et gèrent les erreurs, rendant les sorties LLM fiables pour le traitement en aval.

# JSONParser

Extrait et parse le JSON des réponses LLM, même lorsqu'il est enveloppé dans des blocs de code markdown ou mélangé avec du texte.

import { JSONParser } from '@orka-js/tools';
 
const parser = new JSONParser({ strict: false });
 
// Réponse LLM avec JSON dans markdown
const llmOutput = `Voici les données que vous avez demandées:
 
//json
//{
//  "name": "Alice",
//  "age": 30,
//  "skills": ["TypeScript", "Python"]
//}
 
const data = parser.parse(llmOutput);
console.log(data);
// { name: 'Alice', age: 30, skills: ['TypeScript', 'Python'] }
 
// Récupère les instructions de format pour le LLM
const instructions = parser.getFormatInstructions();
console.log(instructions);

Extraction Intelligente

JSONParser extrait automatiquement le JSON des blocs de code markdown, gère les objets et les tableaux, et fournit des messages d'erreur clairs en cas d'échec du parsing.

# StructuredOutputParser

Parse et valide les sorties LLM par rapport à un schéma Zod pour des données structurées type-safe.

📦 Installation Requise

StructuredOutputParser nécessite Zod pour la validation de schéma :

npm install zod

import { StructuredOutputParser } from '@orka-js/tools';
import { z } from 'zod';
 
// Définit le schéma
const schema = z.object({
  name: z.string().describe('Person name'),
  age: z.number().describe('Age in years'),
  email: z.string().email().describe('Email address'),
  skills: z.array(z.string()).describe('List of skills')
});
 
// Crée le parseur
const parser = StructuredOutputParser.fromZodSchema(schema);
 
// Récupère les instructions de format pour le LLM
const instructions = parser.getFormatInstructions();
const prompt = `${isEn ? "Extract person info from this text:" : "Extrait les informations de cette personne:"} "Alice is 30 years old..."
 
${instructions}`;
 
const llmResponse = await llm.generate(prompt);
 
// Parse et valide
try {
  const data = parser.parse(llmResponse.content);
  console.log(data);
  // { name: 'Alice', age: 30, email: 'alice@example.com', skills: [...] }
  // ✅ Type-safe and validated
} catch (error) {
  console.error('Validation failed:', error.message);
}

Parsing Naïf

JSON Non Contrôlé

JSON.parse(rawResponse);

Risque d'hallucination élevé
Échecs silencieux au runtime
Casting de type manuel requis

Extraction Structurée

Schéma Contractuel

parser.parse(llmOutput);

Type-Safe via Zod
Capture d'erreurs automatique
Prêt pour la mise en prod

Intégrité des Données

Schema Validated

# ListParser

Parse les listes des sorties LLM, gérant automatiquement les puces, les numéros et les séparateurs personnalisés.

import { ListParser } from '@orka-js/tools';
 
const parser = new ListParser({
  separator: '\n',  // Split by newline (default)
  trim: true        // Remove whitespace
});
 
const llmOutput = `Here are the top programming languages:
 
- TypeScript
- Python
- Go
- Rust
`;
 
const items = parser.parse(llmOutput);
console.log(items);
// ['TypeScript', 'Python', 'Go', 'Rust']
 
// Fonctionne aussi avec des listes numérotées
const numbered = `1. First item
2. Second item
3. Third item`;
 
const items2 = parser.parse(numbered);
// ['First item', 'Second item', 'Third item']
 
// Séparateur personnalisé
const csvParser = new ListParser({ separator: ',' });
const csv = 'apple, banana, orange';
console.log(csvParser.parse(csv));
// ['apple', 'banana', 'orange']

# AutoFixParser

Enveloppe n'importe quel parseur et réessaie automatiquement avec correction LLM lorsque le parsing échoue.

import { AutoFixParser, StructuredOutputParser } from '@orka-js/tools';
import { z } from 'zod';
 
const schema = z.object({
  name: z.string(),
  age: z.number()
});
 
const baseParser = StructuredOutputParser.fromZodSchema(schema);
 
const autoFixParser = new AutoFixParser({
  parser: baseParser,
  maxRetries: 3,
  llm: orka.getLLM()
});
 
// Sortie LLM malformée
const badOutput = `{
  "name": "Alice",
  "age": "thirty"  // ❌ Devrait être un nombre
}`;
 
// Essaye de parser avec auto-fix
try {
  const data = await autoFixParser.parseWithRetry(badOutput);
  console.log(data);
  // { name: 'Alice', age: 30 }  ✅ Corrigé automatiquement
} catch (error) {
  console.error('Échec après les tentatives:', error);
}

Tentative de Parsing

Le moteur applique le schéma initial (JSON/Zod) à la réponse brute du LLM.

Step 1: ParseValidation Phase

Capture d'Erreur

Si une erreur survient, la trace et la sortie originale sont préservées.

Step 2: DetectFailure Handling

Réflexion du LLM

Un sub-prompt instruit le LLM de corriger sa sortie selon le journal d'erreurs.

Step 3: CorrectSelf-Healing

Validation Finale

La sortie corrigée est re-parsée. Le cycle continue jusqu'au succès ou maxRetries.

Step 4: RetryCycle Repeat

# XMLParser

Parse les sorties balisées XML des LLMs. Utile quand vous avez besoin de plusieurs champs nommés sans formatage JSON, ce que certains LLMs gèrent plus naturellement avec des balises XML.

import { XMLParser } from '@orka-js/tools';
 
// Usage de base — extrait toutes les balises XML
const parser = new XMLParser();
 
const llmOutput = `Voici mon analyse:
 
<summary>Le produit a un potentiel de marché fort</summary>
<sentiment>positive</sentiment>
<confidence>0.92</confidence>
<reasoning>Basé sur les tendances du marché et l'analyse des concurrents, le produit comble un vide clair.</reasoning>`;
 
const data = parser.parse(llmOutput);
console.log(data);
// {
//   summary: 'Le produit a un potentiel de marché fort',
//   sentiment: 'positive',
//   confidence: '0.92',
//   reasoning: 'Basé sur les tendances du marché et l'analyse des concurrents...'
// }
 
// Mode strict — exige des balises spécifiques
const strictParser = new XMLParser({
  tags: ['summary', 'sentiment', 'confidence'],
  strict: true  // Throws if any required tag is missing
});
 
const result = strictParser.parse(llmOutput);
// ✅ Valide que toutes les balises requises sont présentes
 
// Obtient les instructions de format pour le LLM
console.log(strictParser.getFormatInstructions());
// "Votre réponse doit utiliser les balises XML suivantes:
//  <summary>value</summary>
//  <sentiment>value</sentiment>
//  <confidence>value</confidence>"

# CSVParser

Parse les sorties au format CSV en tableaux d'objets. Gère les champs entre guillemets, les séparateurs personnalisés et les en-têtes prédéfinis optionnels. Idéal pour l'extraction de données tabulaires des LLMs.

import { CSVParser } from '@orka-js/tools';
 
// Détection automatique des en-têtes depuis la première ligne
const parser = new CSVParser();
 
const llmOutput = `nom,role,expérience
Alice,Ingénieure,5 ans
Bob,Designer,3 ans
Charlie,Manager,8 ans`;
 
const data = parser.parse(llmOutput);
console.log(data);
// [
//   { name: 'Alice', role: 'Engineer', experience: '5 years' },
//   { name: 'Bob', role: 'Designer', experience: '3 years' },
//   { name: 'Charlie', role: 'Manager', experience: '8 years' }
// ]
 
// En-têtes prédéfinis (pas de ligne d'en-tête dans les données)
const noHeaderParser = new CSVParser({
  headers: ['product', 'price', 'stock'],
  separator: ';',  // Custom separator
  strict: true     // Enforce column count
});
 
const tabData = `iPhone;999;true
MacBook;1999;false`;
 
console.log(noHeaderParser.parse(tabData));
// [
//   { product: 'iPhone', price: '999', stock: 'true' },
//   { product: 'MacBook', price: '1999', stock: 'false' }
// ]
 
// Gère les champs entre guillemets avec des virgules
const quotedCSV = `name,description
"Smith, John","Senior engineer, 10+ years"`;
console.log(parser.parse(quotedCSV));
// [{ name: 'Smith, John', description: 'Senior engineer, 10+ years' }]

# CommaSeparatedListParser

Un parseur spécialisé pour les listes séparées par des virgules. Plus simple que CSVParser quand vous avez juste besoin d'une liste plate de valeurs. Supporte la déduplication et le nettoyage automatique.

import { CommaSeparatedListParser } from '@orka-js/tools';
 
const parser = new CommaSeparatedListParser({
  trim: true,              // Supprime les espaces
  removeDuplicates: false  // Conserve les doublons
});
 
const llmOutput = 'TypeScript, Python, Go, Rust, JavaScript';
const items = parser.parse(llmOutput);
console.log(items);
// ['TypeScript', 'Python', 'Go', 'Rust', 'JavaScript']
 
// Avec déduplication
const deduper = new CommaSeparatedListParser({ removeDuplicates: true });
const dupes = 'apple, banana, apple, orange, banana';
console.log(deduper.parse(dupes));
// ['apple', 'banana', 'orange']
 
// Instructions de format pour le LLM
console.log(parser.getFormatInstructions());
// "Votre réponse doit être une liste séparée par des virgules de valeurs.
//  Example: item1, item2, item3"

Exemple Complet

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import { StructuredOutputParser, AutoFixParser } from '@orka-js/tools';
import { z } from 'zod';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: /* ... */
});
 
// Définit le schéma
const productSchema = z.object({
  name: z.string(),
  price: z.number(),
  category: z.enum(['electronics', 'clothing', 'food']),
  inStock: z.boolean(),
  tags: z.array(z.string())
});
 
// Crée un parseur avec correction automatique
const baseParser = StructuredOutputParser.fromZodSchema(productSchema);
const parser = new AutoFixParser({
  parser: baseParser,
  maxRetries: 2,
  llm: orka.getLLM()
});
 
// Génère une sortie structurée
const prompt = `Extrait les informations du produit de cette description:
L'iPhone 15 Pro coûte 999$ et est actuellement disponible. 
C'est un produit électronique avec les tags: smartphone, apple, 5g
 
${baseParser.getFormatInstructions()}`;
 
const response = await orka.generate(prompt);
 
// Parse avec validation et correction automatique
const product = await parser.parseWithRetry(response);
 
console.log(product);
// {
//   name: 'iPhone 15 Pro',
//   price: 999,
//   category: 'electronics',
//   inStock: true,
//   tags: ['smartphone', 'apple', '5g']
// }
// ✅ Type-safe, validé et corrigé automatiquement si nécessaire

Comparaison

Parseur de Sortie	Logique d'Extraction	Stratégie de Validation
`StructuredOutput`Enterprise	Objets Type-safe ComplexesMapping via Zod	Vérification
`AutoFixParser`Resilient	Données Auto-correctricesRéparation LLM récursive	Vérification
`JSONParser`Classic	Données Objets StandardParsing JSON strict	Vérification
`XMLParser`Robust	Multi-champs balisésIsolation de balises	Vérification
`ListParser`Clean	Collections de TableauxDécoupage par Regex	Vérification
`CSVParser`Legacy	Flux de Données TabulairesExtraction colonnalaire	Vérification
`CSVList`Light	Tags & Énumérations rapidesDélimité par virgules	Vérification

Bonnes Pratiques

1. Incluez les Instructions de Format

Ajoutez toujours parser.getFormatInstructions() à vos prompts pour guider le LLM.

2. Utilisez Zod pour les Schémas Complexes

StructuredOutputParser avec Zod fournit la sécurité des types, la validation et des messages d'erreur clairs.

3. Utilisez AutoFix avec Parcimonie

AutoFixParser fait des appels LLM supplémentaires. Utilisez-le pour les données critiques ou lorsque les sorties LLM sont peu fiables.

Imports Tree-shakeable

// ✅ Importez uniquement ce dont vous avez besoin
import { StructuredOutputParser } from '@orka-js/tools';
import { AutoFixParser } from '@orka-js/tools';
import { XMLParser } from '@orka-js/tools';
import { CSVParser } from '@orka-js/tools';
import { CommaSeparatedListParser } from '@orka-js/tools';
 
// ✅ Ou importez depuis l'index
import { JSONParser, ListParser, XMLParser, CSVParser } from '@orka-js/tools';