Chargeurs de Documents

Chargez des données depuis diverses sources : PDF, CSV, JSON, Markdown, fichiers texte et dossiers complets.

Vue d'ensemble

Les chargeurs de documents transforment les données brutes de différentes sources en un format Document unifié qu'Orka AI peut traiter. Chaque chargeur gère des types de fichiers spécifiques et une logique d'extraction.

Qu'est-ce qu'un Document ?

Tous les loaders retournent un tableau d'objets Document avec cette structure :

interface Document {
  id: string;              // Identifiant unique
  content: string;         // Le contenu texte réel
  metadata: {
    source?: string;       // Chemin du fichier ou URL
    loader?: string;       // Nom du chargeur
    ...customFields        // Vos métadonnées personnalisées
  };
}

# TextLoader

Charge des fichiers texte brut avec support d'encodage personnalisé. Le loader le plus simple — lit un fichier et retourne son contenu comme un seul document.

import { TextLoader } from '@orka-js/tools';
 
const loader = new TextLoader('./document.txt', {
  encoding: 'utf-8',
  metadata: { source: 'documentation' }
});
 
const documents = await loader.load();
// [{ id: '...', content: '...', metadata: { source: 'documentation', loader: 'TextLoader' } }]

Paramètres du Constructeur

path: string

Chemin absolu ou relatif vers le fichier texte.

options.encoding?: string

Encodage de caractères (défaut : 'utf-8'). Supporte 'utf-8', 'ascii', 'latin1', etc.

options.metadata?: Record<string, unknown>

Métadonnées personnalisées à attacher au document. Utile pour la catégorisation, le filtrage ou le suivi.

# CSVLoader

Parse des fichiers CSV avec support de séparateurs personnalisés, sélection de colonnes et extraction de contenu. Chaque ligne devient un document séparé, ce qui le rend parfait pour charger des données structurées comme des catalogues de produits, des listes d'utilisateurs ou des bases de FAQ.

import { CSVLoader } from '@orka-js/tools';
 
// Option 1: Utiliser une colonne spécifique comme contenu
const loader = new CSVLoader('./data.csv', {
  separator: ',',
  contentColumn: 'description',  // Utiliser cette colonne comme contenu du document
  metadata: { type: 'product_data' }
});
 
// Option 2: Combiner plusieurs colonnes
const loader2 = new CSVLoader('./users.csv', {
  columns: ['name', 'bio', 'interests'],  // Combine these columns
});
 
const documents = await loader.load();
// Each row becomes a separate document

Parsing CSV Avancé

Conçu pour l'ingestion de données structurées

RFC 4180

Intégrité des Quotes

Analyse avec précision les champs contenant des virgules ou des sauts de ligne.

Flexible

Délimiteurs Dynamiques

Support complet : virgules, points-virgules ou tabulations (TSV).

RAG-Ready

Auto-Métadonnées

Convertit automatiquement les colonnes en tags de métadonnées pour votre Vector Store.

# JSONLoader

Charge des fichiers JSON ou objets avec support JSONPath pour l'extraction de données imbriquées. Gère à la fois les objets uniques et les tableaux, avec un mapping flexible des champs pour le contenu et les métadonnées.

import { JSONLoader } from '@orka-js/tools';
 
// Charger depuis un fichier
const loader = new JSONLoader('./data.json', {
  contentField: 'text',           // Utiliser ce champ comme contenu
  metadataFields: ['author', 'date'],  // Extraire ces champs comme métadonnées
  jsonPath: '$.articles'          // Extraire le tableau imbriqué
});
 
// Charger depuis un objet
const data = [
  { text: 'Article 1', author: 'Alice' },
  { text: 'Article 2', author: 'Bob' }
];
const loader2 = new JSONLoader(data, {
  contentField: 'text'
});
 
const documents = await loader.load();

# MarkdownLoader

Charge des fichiers Markdown avec extraction du frontmatter et parsing des en-têtes. Parfait pour la documentation, les articles de blog ou tout contenu avec des métadonnées frontmatter YAML.

import { MarkdownLoader } from '@orka-js/tools';
 
const loader = new MarkdownLoader('./README.md', {
  removeFrontmatter: true,   // Extract YAML frontmatter
  includeHeaders: true,      // Extract all headers as metadata
  metadata: { type: 'documentation' }
});
 
const documents = await loader.load();
// Frontmatter fields are added to metadata
// Headers are available in metadata.headers

Exemple Markdown avec Frontmatter

---
title: Getting Started
author: Alice
date: 2024-01-15
---
 
# Introduction
 
This is the content...

# PDFLoader

Extrait le texte des fichiers PDF avec sélection de pages et extraction de métadonnées. Chaque page devient un document séparé avec suivi du numéro de page, idéal pour les articles de recherche, rapports ou manuels.

📦 Installation Requise

PDFLoader nécessite le package pdf-parse :

npm install pdf-parse

import { PDFLoader } from '@orka-js/tools';
 
// Charger le PDF entier
const loader = new PDFLoader('./document.pdf', {
  metadata: { source: 'research_paper' }
});
 
// Charger des pages spécifiques
const loader2 = new PDFLoader('./report.pdf', {
  pages: [1, 2, 3],      // Seulement les pages 1, 2, 3
  maxPages: 10           // Ou limiter aux 10 premières pages
});
 
const documents = await loader.load();
// Chaque page devient un document séparé avec le numéro de page dans les métadonnées

# DirectoryLoader

Charge récursivement tous les fichiers supportés d'un dossier avec détection automatique du chargeur. Le loader le plus puissant — scanne des arborescences de répertoires entières, détecte les types de fichiers et applique automatiquement le loader approprié.

import { DirectoryLoader } from '@orka-js/tools';
 
const loader = new DirectoryLoader('./docs', {
  recursive: true,                    // Scanner les sous-dossiers
  glob: '*.md',                       // Filtrer par motif
  exclude: ['node_modules', '.git'],  // Exclure les dossiers
  metadata: { project: 'orka-docs' }
});
 
const documents = await loader.load();
// Détecte automatiquement et utilise le bon chargeur pour chaque type de fichier

Extension de Fichier	Chargeur Interne	Stratégie
`.txt`	`TextLoader`	Plain Text
`.md, .mdx`	`MarkdownLoader`	Structure Aware
`.csv`	`CSVLoader`	Row-to-Document
`.json, .jsonl`	`JSONLoader`	Object Mapping
`.ts, .js, .py`	`TextLoader`	Raw Code Ingestion

Utilisation avec Knowledge

Les chargeurs s'intègrent parfaitement avec le système Knowledge d'Orka. Voici un pipeline complet du chargement de documents à la création d'une base de connaissances consultable :

create-knowledge-base.ts

import { createOrka } from 'orkajs';
import { DirectoryLoader } from '@orka-js/tools';
import { RecursiveCharacterTextSplitter } from '@orka-js/tools';
 
const orka = createOrka({ /* config */ });
 
// Charger les documents
const loader = new DirectoryLoader('./knowledge-base');
const documents = await loader.load();
 
// Diviser en chunks
const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200
});
const chunks = splitter.splitDocuments(documents);
 
// Créer la base de connaissances
await orka.knowledge.create({
  name: 'my-knowledge',
  source: documents.map(d => ({ text: d.content, metadata: d.metadata }))
});

Imports Tree-shakeable

Importez uniquement ce dont vous avez besoin pour minimiser la taille du bundle :

// ❌ Importe tout
import { CSVLoader, PDFLoader } from 'orkajs';
 
// ✅ Tree-shakeable - ne bundle que CSVLoader
import { CSVLoader } from '@orka-js/tools';
 
// ✅ Importer tous les chargeurs depuis l'index
import { CSVLoader, PDFLoader, JSONLoader } from '@orka-js/tools';

Chargeurs basés sur API

Chargez des données depuis des services externes via leurs APIs. Ces chargeurs nécessitent des identifiants d'authentification.

# NotionLoader

Charge des pages et bases de données depuis Notion. Extrait le contenu texte enrichi et les propriétés.

import { NotionLoader } from '@orka-js/tools';
 
const loader = new NotionLoader({
  apiKey: process.env.NOTION_API_KEY!,
  pageIds: ['page-id-1', 'page-id-2'],
  // Ou charger depuis des bases de données
  databaseIds: ['database-id'],
  includeChildPages: true,
  maxDepth: 3,
});
 
const documents = await loader.load();
// Chaque page devient un document avec titre, contenu et propriétés Notion

# SlackLoader

Charge des messages depuis des canaux Slack avec support des threads et filtrage par date.

import { SlackLoader } from '@orka-js/tools';
 
const loader = new SlackLoader({
  token: process.env.SLACK_BOT_TOKEN!,
  channelIds: ['C123456', 'C789012'],
  startDate: new Date('2024-01-01'),
  endDate: new Date(),
  includeThreads: true,
  includeFiles: false,
  limit: 1000,
});
 
const documents = await loader.load();
// Chaque message devient un document avec info canal et timestamp

# GitHubLoader

Charge des fichiers depuis des dépôts GitHub. Parfait pour charger de la documentation, du code ou des fichiers README.

import { GitHubLoader } from '@orka-js/tools';
 
const loader = new GitHubLoader({
  token: process.env.GITHUB_TOKEN, // Optionnel pour les repos publics
  owner: 'orka-ai',
  repo: 'orkajs',
  branch: 'main',
  path: 'docs',
  recursive: true,
  fileExtensions: ['.md', '.txt', '.ts'],
  excludePaths: ['node_modules', 'dist'],
  includeReadme: true,
});
 
const documents = await loader.load();
// Chaque fichier devient un document avec chemin, SHA et info repo

# GoogleDriveLoader

Charge des fichiers depuis Google Drive. Supporte Google Docs, Sheets et fichiers réguliers.

import { GoogleDriveLoader } from '@orka-js/tools';
 
const loader = new GoogleDriveLoader({
  credentials: {
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
  },
  folderId: 'folder-id', // Charger tous les fichiers du dossier
  // Ou des fichiers spécifiques
  fileIds: ['file-id-1', 'file-id-2'],
  recursive: true,
  maxFiles: 100,
  mimeTypes: ['text/plain', 'application/vnd.google-apps.document'],
});
 
const documents = await loader.load();
// Google Docs sont exportés en texte, fichiers réguliers téléchargés

Note de Sécurité : Ne codez jamais les clés API ou tokens en dur. Utilisez des variables d'environnement et suivez le principe du moindre privilège lors de la création des identifiants API.