SDK TypeScript — @ignitionai/sdk

Le SDK TypeScript officiel d'IgnitionRAG permet d'intégrer la puissance du RAG dans vos applications en quelques lignes de code. Zéro dépendance, compatible Node.js 18+, Bun et Deno.

Installation

Installez le SDK avec votre gestionnaire de packages préféré :

npm install @ignitionai/sdk

ou

bun add @ignitionai/sdk

Démarrage rapide

Voici un premier exemple pour vérifier que tout fonctionne :

import { IgnitionAI } from '@ignitionai/sdk';

const client = new IgnitionAI({
  apiKey: 'ign_votre_cle_api',
});

// Premier appel RAG Chat
const response = await client.chat.send({
  collectionId: 'votre-collection-id',
  query: 'Qu\'est-ce que le RAG ?',
});

console.log(response.answer);
console.log(`Sources: ${response.sources.length}`);

Configuration du Client

Le client IgnitionAI accepte plusieurs options de configuration.

Configuration de base

import { IgnitionAI } from '@ignitionai/sdk';

const client = new IgnitionAI({
  apiKey: 'ign_votre_cle_api',
});

Variable d'environnement

Si vous définissez la variable d'environnement IGNITION_API_KEY, le SDK l'utilise automatiquement — pas besoin de passer apiKey au constructeur.

// .env
IGNITION_API_KEY=ign_votre_cle_api

// Votre code — pas besoin de passer apiKey
const client = new IgnitionAI();

Toutes les options

Voici la liste complète des options disponibles :

const client = new IgnitionAI({
  apiKey: 'ign_xxx',          // Clé API (ou IGNITION_API_KEY env)
  baseURL: 'https://ignitionrag.com', // URL de base de l'API
  maxRetries: 2,              // Nombre de tentatives sur erreur
  timeout: 60000,             // Timeout en ms (60s par défaut)
  fetch: customFetch,         // Implémentation fetch personnalisée
});

Fetch personnalisé

Pour les environnements sans fetch natif (Node.js < 18), vous pouvez fournir votre propre implémentation :

import fetch from 'node-fetch';

const client = new IgnitionAI({
  fetch: fetch as any,
});

RAG Chat

Le RAG Chat permet d'interroger vos collections de documents avec la puissance de l'IA. Le SDK propose 4 modes d'utilisation selon vos besoins.

Non-streaming

Le mode le plus simple — envoie une requête et reçoit la réponse complète d'un coup.

const response = await client.chat.send({
  collectionId: 'votre-collection-id',
  query: 'Quelles sont les tendances du marché ?',
  history: [
    { role: 'user', content: 'Bonjour' },
    { role: 'assistant', content: 'Bonjour ! Comment puis-je vous aider ?' },
  ],
});

console.log(response.answer);           // Réponse complète
console.log(response.sources);           // Sources utilisées
console.log(response.pipelineMetrics);   // Métriques du pipeline

Champs de la réponse

Streaming

Le mode streaming permet de recevoir la réponse en temps réel, chunk par chunk. Idéal pour les interfaces chat.

const stream = client.chat.stream({
  collectionId: 'votre-collection-id',
  query: 'Explique le concept de RAG',
});

for await (const event of stream) {
  switch (event.type) {
    case 'chunk':
      process.stdout.write(event.content);
      break;
    case 'sources':
      console.log('\nSources:', event.sources.length);
      break;
    case 'metrics':
      console.log('Temps total:', event.pipelineMetrics.totalTimeMs, 'ms');
      break;
    case 'done':
      console.log('\nTerminé !');
      break;
  }
}

Événements du stream

Text Stream

Si vous ne voulez que le texte (sans les sources ni les métriques), utilisez toTextStream() pour un code plus concis :

const stream = client.chat.stream({
  collectionId: 'votre-collection-id',
  query: 'Résume ce document',
});

for await (const text of stream.toTextStream()) {
  process.stdout.write(text);
}

Streaming Progressif

Le mode progressif vous permet de suivre chaque étape du pipeline RAG en temps réel : amélioration de la requête, recherche, génération. Idéal pour les interfaces avancées.

const stream = client.chat.streamProgressive({
  collectionId: 'votre-collection-id',
  query: 'Analyse comparative des solutions',
});

for await (const event of stream) {
  switch (event.type) {
    case 'stage':
      console.log(`⏱️ ${event.stage} (${event.elapsed}ms)`);
      break;
    case 'enhancement':
      console.log(`🔍 Requête améliorée: ${event.enhanced}`);
      break;
    case 'sources':
      console.log(`📚 ${event.sources.length} sources trouvées en ${event.retrievalTimeMs}ms`);
      break;
    case 'chunk':
      process.stdout.write(event.content);
      break;
    case 'citation':
      console.log(`[${event.index}]`);
      break;
    case 'metrics':
      console.log('\n📊 Pipeline complet:', event.pipelineMetrics.totalTimeMs, 'ms');
      break;
  }
}

Étapes du pipeline

Collecte de la réponse complète

Utilisez getFullResponse() pour collecter toute la réponse d'un stream en une seule fois :

const stream = client.chat.stream({
  collectionId: 'votre-collection-id',
  query: 'Résumé exécutif',
});

const result = await stream.getFullResponse();
console.log(result.text);       // Texte complet
console.log(result.sources);    // Toutes les sources
console.log(result.metrics);    // Métriques pipeline

Agent Chat

L'Agent Chat permet de discuter avec vos agents IA configurés. Les agents peuvent utiliser des outils (tool calls) pour effectuer des actions comme rechercher dans des collections, naviguer sur le web, ou appeler des serveurs MCP.

const stream = client.agentChat.stream('votre-agent-id', {
  query: 'Quels sont les derniers articles sur le RAG ?',
  sessionId: 'session-optionnelle',  // Auto-généré si omis
});

for await (const event of stream) {
  switch (event.type) {
    case 'chunk':
      process.stdout.write(event.content);
      break;
    case 'tool_call':
      console.log(`\n🔧 Outil: ${event.name}`, event.args);
      break;
    case 'tool_result':
      console.log(`✅ Résultat: ${event.result.substring(0, 100)}...`);
      break;
    case 'sources':
      console.log(`\n📚 Sources: ${event.sources.length}`);
      break;
    case 'done':
      console.log('\nConversation terminée.');
      break;
  }
}

Événements de l'Agent Chat

Collecte de la réponse complète

const stream = client.agentChat.stream('votre-agent-id', {
  query: 'Analyse les tendances',
});

const result = await stream.getFullResponse();
console.log(result.text);        // Réponse complète
console.log(result.sources);     // Sources
console.log(result.toolCalls);   // Appels d'outils effectués

Collections

Les collections sont des ensembles de documents indexés pour la recherche RAG. Le SDK permet de les gérer programmatiquement.

const collections = await client.collections.list();

for (const col of collections) {
  console.log(`${col.name} — ${col.documentCount} documents`);
}

// Avec options
const all = await client.collections.list({
  includeShared: true,
  includePublic: true,
});

const collection = await client.collections.get('collection-id');
console.log(collection.name, collection.documentCount);

const collection = await client.collections.create({
  name: 'Ma nouvelle collection',
  description: 'Documents de référence',
  visibility: 'private',  // 'private' | 'shared' | 'public'
});

console.log('Créée:', collection.id);

const results = await client.collections.search('collection-id', {
  query: 'intelligence artificielle',
  limit: 10,
  sourceType: 'document',  // 'document' | 'web' | 'dataset'
  type: 'text',            // 'text' | 'image'
});

for (const result of results.results) {
  console.log(`[${result.score.toFixed(2)}] ${result.content.substring(0, 100)}`);
}

const page = await client.collections.chunks('collection-id', {
  offset: 0,
  limit: 20,
  sourceType: 'document',
  type: 'text',
});

console.log(`${page.total} chunks au total, ${page.hasMore ? 'plus à venir' : 'fin'}`);
for (const chunk of page.chunks) {
  console.log(`[${chunk.type}] ${chunk.content.substring(0, 80)}...`);
}

const stats = await client.collections.stats('collection-id');

console.log('Chunks:', stats.totalChunks);
console.log('Par type:', stats.byType);
console.log('Par source:', stats.bySourceType);
console.log('Top sources:', stats.topSources);

const insights = await client.collections.insights('collection-id');

console.log('Sujets principaux:', insights.mainTopics);
console.log('Conclusions clés:', insights.keyFindings);
console.log('Méthodologie:', insights.methodology);
console.log('Dates importantes:', insights.importantDates);

const updated = await client.collections.update('collection-id', {
  name: 'Nouveau nom',
  description: 'Nouvelle description',
});

// Suppression douce (archivage)
await client.collections.delete('collection-id');

// Suppression définitive
await client.collections.delete('collection-id', true);

Agents

Les agents sont des assistants IA configurés avec des instructions, un modèle, et des outils. Le SDK permet de les gérer et de générer automatiquement leur configuration.

const agents = await client.agents.list();

for (const agent of agents) {
  console.log(`${agent.name} — ${agent.model}`);
}

const agent = await client.agents.get('agent-id');
console.log(agent.name, agent.systemPrompt);

const agent = await client.agents.create({
  name: 'Assistant Documentation',
  description: 'Agent spécialisé dans la documentation technique',
  collectionId: 'collection-id',
  systemPrompt: 'Tu es un assistant expert en documentation technique.',
  model: 'gpt-4o',
  temperature: 0.3,
  maxTokens: 4096,
  topK: 10,
  scoreThreshold: 0.7,
});

console.log('Créé:', agent.id);

const config = await client.agents.generate({
  description: 'Un assistant qui aide les développeurs à comprendre notre API REST',
  collectionId: 'api-docs-collection',
  language: 'fr',
});

console.log('Nom suggéré:', config.name);
console.log('Prompt système:', config.systemPrompt);
console.log('Modèle:', config.model);
console.log('Température:', config.temperature);

// Créer l'agent avec la config générée
const agent = await client.agents.create({
  ...config,
  collectionId: 'api-docs-collection',
});

const updated = await client.agents.update('agent-id', {
  name: 'Nouveau nom',
  temperature: 0.5,
  maxTokens: 8192,
});

// Suppression douce
await client.agents.delete('agent-id');

// Suppression définitive
await client.agents.delete('agent-id', true);

Ingestion

L'ingestion permet d'ajouter des documents à vos collections. Le SDK supporte 5 méthodes d'ingestion pour couvrir tous les cas d'usage.

const result = await client.ingest.url({
  collectionId: 'collection-id',
  url: 'https://docs.example.com/guide',
  enableMultimodal: true,    // Indexer aussi les images
  enableEnrichment: true,    // Résumé, entités, tags IA
});

console.log(`${result.chunksCount} chunks créés`);
console.log(`${result.imagesCount ?? 0} images indexées`);

const result = await client.ingest.document({
  collectionId: 'collection-id',
  content: 'Le contenu de votre document ici...',
  filename: 'mon-document.txt',
});

console.log(`${result.chunksCount} chunks créés`);

// Dans Node.js
import { readFileSync } from 'fs';

const buffer = readFileSync('./rapport.pdf');
const file = new File([buffer], 'rapport.pdf', { type: 'application/pdf' });

const result = await client.ingest.file({
  collectionId: 'collection-id',
  file,
});

console.log(`${result.chunksCount} chunks créés`);

const result = await client.ingest.crawl({
  collectionId: 'collection-id',
  url: 'https://docs.example.com',
  maxPages: 50,
  maxDepth: 3,
  enableMultimodal: true,
  enableEnrichment: true,
});

console.log(`${result.pagesCount} pages crawlées`);
console.log(`${result.chunksCount} chunks créés`);

const result = await client.ingest.dataset({
  collectionId: 'collection-id',
  datasetId: 'squad',
  config: 'plain_text',
  split: 'train',
  limit: 1000,
  enableEnrichment: true,
});

console.log(`${result.chunksCount} chunks créés`);

MCP (Model Context Protocol)

Le SDK permet d'interagir avec les serveurs MCP configurés sur vos agents. Vous pouvez lister les prompts, lire les ressources, et tester la connectivité.

const prompts = await client.mcp.prompts('agent-id');

for (const prompt of prompts) {
  console.log(`${prompt.name} (${prompt.server})`);
  console.log(`  ${prompt.description}`);
}

const content = await client.mcp.getPrompt('agent-id', {
  server: 'mon-serveur-mcp',
  name: 'summarize',
  arguments: { language: 'fr' },
});

console.log(content.messages);

const resources = await client.mcp.resources('agent-id');

for (const resource of resources) {
  console.log(`${resource.name} — ${resource.uri}`);
  console.log(`  Type: ${resource.mimeType}`);
}

const content = await client.mcp.readResource('agent-id', {
  server: 'mon-serveur-mcp',
  uri: 'resource://docs/readme',
});

console.log(content.text ?? content.blob);

const result = await client.mcp.testServer({
  url: 'https://mon-serveur-mcp.example.com',
  token: 'optionnel-bearer-token',
});

if (result.success) {
  console.log('Connecté ! Outils disponibles:', result.tools);
} else {
  console.error('Erreur:', result.error);
}

Gestion des Erreurs

Le SDK fournit des classes d'erreur typées pour chaque type de problème. Le client effectue automatiquement des retries sur les erreurs transitoires (408, 429, 5xx).

Classes d'erreur

Exemple de gestion d'erreurs

import {
  IgnitionAI,
  AuthenticationError,
  PermissionError,
  RateLimitError,
  NotFoundError,
  APIConnectionError,
} from '@ignitionai/sdk';

const client = new IgnitionAI();

try {
  const response = await client.chat.send({
    collectionId: 'collection-id',
    query: 'Ma question',
  });
  console.log(response.answer);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Clé API invalide. Vérifiez votre clé IgnitionRAG.');
  } else if (error instanceof PermissionError) {
    console.error(`Plan insuffisant: ${error.feature}`);
    console.error(`Upgrade: ${error.upgradeUrl}`);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limit atteint. Retry dans ${error.retryAfter}s`);
  } else if (error instanceof NotFoundError) {
    console.error('Collection introuvable.');
  } else if (error instanceof APIConnectionError) {
    console.error('Problème réseau:', error.message);
  } else {
    throw error;
  }
}

Retries automatiques

Le SDK effectue automatiquement des retries sur les erreurs transitoires avec un backoff exponentiel :

• Codes retryables : 408, 429, 500, 502, 503, 504
• Stratégie : backoff exponentiel (500ms → 1s → 2s → 4s, max 8s) avec ±25% de jitter
• Par défaut : 2 retries maximum (configurable via maxRetries)
• Si le serveur renvoie un header Retry-After, le SDK respecte ce délai

Intégration Vercel AI SDK

Le SDK fournit un adaptateur officiel pour le Vercel AI SDK. Vous pouvez créer un chat IA fonctionnel dans une app Next.js en quelques minutes avec useChat().

Route Handler (API)

Créez une route API Next.js qui convertit le stream IgnitionRAG au format Vercel AI SDK :

// app/api/chat/route.ts
import { IgnitionAI } from '@ignitionai/sdk';
import { toAIStreamResponse } from '@ignitionai/sdk/adapters/vercel-ai';

const client = new IgnitionAI();

export async function POST(req: Request) {
  const { messages } = await req.json();

  const stream = client.chat.stream({
    collectionId: process.env.COLLECTION_ID!,
    query: messages.at(-1).content,
    history: messages.slice(0, -1),
  });

  return toAIStreamResponse(stream);
}

Composant Client (React)

Utilisez useChat() du Vercel AI SDK pour créer l'interface chat :

// components/Chat.tsx
'use client';
import { useChat } from 'ai/react';

export function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat',
  });

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role === 'user' ? 'Vous' : 'IA'}:</strong>
          <p>{m.content}</p>
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Posez une question..."
        />
        <button type="submit">Envoyer</button>
      </form>
    </div>
  );
}