Extraire des champs avec Clairic

Clairic est un modèle d’extraction de System One. Il lit un état partagé — le texte ou le contexte structuré dont vous voulez extraire des valeurs — et une carte de champs typés, puis renvoie une valeur typée par champ. Il ne génère pas de texte libre et ne répond pas aux questions Choice, Score ou Noul.

Utilisez extract({ state, fields }) sur le même client SystemOne que celui de evaluate(). Ne passez pas fields à evaluate(), et ne passez pas questions à extract().

Le nom de modèle public est clairic, du même style que jev et clef. Copiez ce nom, ou le name exact de GET /v1/models lorsque le catalogue le liste. N’ajoutez pas de préfixe.

Prêt pour les questions

Q: How do I use the Clairic SDK?
A: Appelez extract({ state, fields }) avec Clairic pour tirer des champs typés depuis l’état de l’agent. SDK TypeScript ou API HTTP hébergée.

Q: Is Clairic the same as Choice?
A: No. Choice picks among options; Clairic extract returns structured fields you define. Both are part of System One.

Prêt pour les questions

Comment utiliser le SDK Clairic ? Appelez extract({ state, fields }) avec Clairic pour tirer des champs typés depuis l’état de l’agent, via le SDK TypeScript ou l’API HTTP hébergée.

Clairic est-il la même chose que Choice ? Non. Choice choisit parmi des options ; l’extraction Clairic renvoie les champs structurés que vous définissez. Les deux font partie de System One.

Ce que fait l’extraction Clairic

L’extraction lit une source de contexte et renvoie, pour chaque champ défini, une valeur et son incertitude. Elle ne rédige pas de réponse et ne compare pas deux brouillons : c’est une lecture typée d’un état que vous fournissez.

Les crédits d’extraction sont facturés une fois par requête à partir de la taille d’entrée ; le nombre de champs ne change pas le prix.

Installer

L’extraction nécessite core 0.8.0, l’adaptateur hébergé 0.7.0 et le transport Fetch 0.8.0. Les trois résolvent @system-one-ai/core@^0.8.0.

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

systemOneAdapter poste les requêtes d’extraction vers {baseURL}/systemone. L’adaptateur utilise par défaut https://system-one.dev/v1, donc le chemin hébergé est POST https://system-one.dev/v1/systemone avec un corps fields. Le modèle d’extraction par défaut est clairic.

extract({ state, fields })

Enregistrez cet exemple sous extract-invoice.mts :

import {
  createSystemOne, defineFields, textField, numberField, dateField, listField, estimateField,
} from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
if (!apiKey) throw new Error('Set SYSTEM_ONE_API_KEY.');

const client = createSystemOne({
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  apiKey,
  timeoutMs: 30_000,
  maxRetries: 0,
});

const fields = defineFields({
  invoice_number: textField({ instructions: 'The invoice id printed on the document.' }),
  due_date: dateField({ instructions: 'Issue date plus the net payment days.' }),
  total: numberField({ decimals: 2, instructions: 'The total amount due.' }),
  contacts: listField({ items: 'text' }),
  days_to_pay: estimateField({ min: 0, max: 120, step: 1 }),
});

const result = await client.extract({
  model: 'clairic',
  state: [
    'INVOICE INV-2291',
    'From: Northwind Supply',
    'To: Contoso Ltd',
    'Issued: 2026-09-02, net 30',
    'Total due: 1080.00 including shipping',
    'Contact: Dana Ruiz, Priya Shah',
  ].join('\n'),
  fields,
  referenceDate: '2026-10-19',
  options: { includeQuantiles: false },
});

const invoice: string | null = result.answers.invoice_number.value;
console.log({
  model: result.model,
  invoice,
  dueDate: result.answers.due_date.value,
  total: result.answers.total.value,
  contacts: result.answers.contacts.value,
  daysToPay: result.answers.days_to_pay.median,
  truncated: result.truncated,
  usage: result.usage,
});

node --env-file=.env extract-invoice.mts

Schéma des champs

Chaque champ est un objet de la forme fields.<nom> = { "type": <type>, ...extras }. Le champ type est obligatoire. Les clés imbriquées inconnues sont rejetées.

Types autorisés : text, number, date, time, datetime, duration, list, estimate, forecast.

Extras optionnels autorisés, selon le type : instructions, null_threshold, integer, decimals, unit, items, min, max, step, scale, horizon, interval.

state est une chaîne ; elle ne peut être vide que si des images sont envoyées. Le reference_date optionnel de premier niveau est au format YYYY-MM-DD ; l’objet options optionnel est transmis tel quel.

Images et multimodal

Clairic accepte jusqu’à 4 images, 4 MiB décodés par image et 8 MiB décodés au total. Les formats acceptés sont PNG, JPEG et WebP intégrés en base64 (data URL ou { mediaType, base64 }). Les URL distantes, l’audio et la vidéo ne sont pas pris en charge.

Le plafond de corps pour les modèles compatibles avec les images est de 13 631 488 octets (13 Mo) ; le plafond texte seul est de 65 536 octets.

import { readFile } from 'node:fs/promises';
import { createSystemOne, textField, type ImageInput } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const imagePath = process.argv[2];
if (!apiKey || !imagePath) throw new Error('Set SYSTEM_ONE_API_KEY and supply a PNG path.');

const images: readonly ImageInput[] = [{
  mediaType: 'image/png',
  base64: (await readFile(imagePath)).toString('base64'),
}];

const client = createSystemOne({
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  apiKey,
  timeoutMs: 30_000,
  maxRetries: 0,
});

const result = await client.extract({
  model: 'clairic',
  state: '',
  images,
  fields: { invoice_number: textField() },
});
console.log(result.answers.invoice_number.value);

L’adaptateur SDK hébergé publié est limitement texte ; utilisez HTTP pour les images de décision hébergées, et systemOneAdapter@0.7.0 encode extract(), images comprises. Les images de décision Clé/Clef Flash/Clef Omni hébergées passent par Fetch.

Corps HTTP hébergé

Les noms de champs en camelCase dans le SDK deviennent snake_case dans la requête HTTP (referenceDate → reference_date). Voici le corps accepté par POST /v1/systemone pour la même tâche :

POST /v1/systemone
Authorization: Bearer $SYSTEM_ONE_API_KEY
Content-Type: application/json

{
  "model": "clairic",
  "state": "Invoice INV-2291 from Northwind Supply, issued 2026-09-02.",
  "fields": {
    "invoice_number": { "type": "text", "instructions": "The invoice id" },
    "total": { "type": "number", "decimals": 2 },
    "contacts": { "type": "list", "items": "text" }
  },
  "reference_date": "2026-10-20"
}

Erreurs

Les erreurs d’extraction utilisent les mêmes champs APIError (statusCode, requestId, retryAfterMs) que les autres appels. Une requête d’extraction rejetée à l’admission (format d’image, taille, capacité du modèle) ne réserve aucun crédit ; une requête valide qui échoue plus tard suit les règles de remboursement et de rapprochement habituelles. Voir Codes d’erreur API.

Liens internes : Documentation du SDK, Choisir un modèle, Référence API, Primitives de décision, Démarrer avec le SDK TypeScript.