Mit Clairic Felder extrahieren

Clairic ist ein System One Extraktions-Modell. Es liest einen gemeinsamen State — den Text oder strukturierten Kontext, aus dem Werte entnommen werden sollen — und eine Map typisierter Felder und liefert dann pro Feld einen typisierten Wert zurück. Es erzeugt keinen Freitext und beantwortet keine Choice-, Score- oder Noul-Fragen.

Verwenden Sie extract({ state, fields }) auf demselben SystemOne-Client, den Sie für evaluate() nutzen. Geben Sie nicht fields an evaluate() und nicht questions an extract().

Der öffentliche Modellname ist clairic, im gleichen Stil wie jev und clef. Übernehmen Sie diesen Namen oder den exakten name aus GET /v1/models, wenn der Katalog ihn listet. Fügen Sie dem Modellnamen kein Präfix hinzu.

Probieren Sie dieselbe Rechnungsaufgabe in der angemeldeten Demo zur Rechnungsextraktion. Modelltatsachen und Credit-Raten stehen auf der Clairic-Modellseite.

Bereit für Fragen

Q: How do I use the Clairic SDK?
A: Rufen Sie extract({ state, fields }) mit Clairic auf, um typisierte Felder aus dem Agent-State zu ziehen. Nutzen Sie das TypeScript-SDK oder die gehostete HTTP-API.

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.

Installation

Extraktion benötigt Core 0.8.0, den gehosteten Adapter 0.7.0 und den Fetch-Transport 0.8.0. Alle drei lösen @system-one-ai/core@^0.8.0 auf.

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 sendet Extraktionsanfragen an {baseURL}/systemone. Der Adapter-Standard ist https://system-one.dev/v1, der gehostete Pfad ist also POST https://system-one.dev/v1/systemone mit einem fields-Body. Das Standard-Extraktionsmodell ist clairic.

Eine Rechnung extrahieren

Speichern Sie als extract-invoice.mts. Setzen Sie SYSTEM_ONE_API_KEY auf einen System-One-Plattformschlüssel. Jeder Lauf startet eine neue abrechnungspflichtige Operation.

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

createSystemOne() gibt eine SystemOne-Instanz zurück. new SystemOne({ ... }) ist derselbe Konstruktor. defineFields() erhält die literalen Feld-IDs für ExtractRequest, ExtractResult und FieldAnswers.

Anfrage

Core validiert Feldnamen, typabhängige Eigenschaften und die Bilddarstellung vor dem Versand der Anfrage. Der vollständige JSON-Anfragebody darf 13MB nicht überschreiten (der Katalog kann ein strengeres Limit setzen). Adapter ohne supportsExtract: true lehnen extract() mit UnsupportedFeatureError vor jeder I/O ab.

Feldtypen

Die Factories werden aus @system-one-ai/core exportiert. Inline-Objekte wie { type: 'text' } sind ebenfalls gültig.

Jedes Feld darf instructions enthalten und, außer bei Listen, nullThreshold. Listen dürfen unit und decimals enthalten.

import {
  defineFields, dateTimeField, durationField, forecastField, timeField,
  type ExtractRequest, type ExtractResult, type FieldAnswers,
} from '@system-one-ai/core';

const more = defineFields({
  opens: timeField(),
  signed: dateTimeField(),
  delay: durationField({ unit: 'days' }),
  travelers: forecastField({ min: 500_000, max: 4_000_000, horizon: 1, interval: 'day' }),
});

type MoreRequest = ExtractRequest<typeof more>;
type MoreResult = ExtractResult<typeof more>;
type MoreAnswers = FieldAnswers<typeof more>;

Antwort

Auf jeder Antwort ist nur value garantiert. Skalare Typen melden zusätzlich guess, confidence und pNull, wenn das Modell sie sendet. Text kann einen span enthalten. Listen enthalten value und optionale spans. Schätzungen und Prognosen enthalten mean, median, p10, p90, pBelow und pAbove; sie verwenden nicht confidence / pNull. Der value einer Prognose ist ein Array mit einem Wert pro Schritt (horizon Schritte).

truncated ist immer ein Boolean. usage normalisiert die Tokenzahlen zu inputTokens, outputTokens, totalTokens und optional stateTokens, imageTokens, schemaTokens, passes. Optionale Zahlen, die nicht zurückgegeben wurden, erscheinen nicht im Ergebnis.

result.model kann von der angeforderten ID abweichen. Notieren Sie beide.

Bilder mit extract()

Clairic akzeptiert bis zu vier PNG-, JPEG- oder WebP-Bilder in extract(). state darf '' sein, wenn Bilder vorhanden sind. ImageInput wird von Core exportiert: eine eingebettete base64-Data-URL oder { mediaType: 'image/png', base64: '...' }.

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);

Das ist Extraktion, keine Entscheidung. Entscheidungsbilder auf gehostetem Clef nutzen weiterhin Fetch, weil systemOneAdapter keine evaluate()-Bilder kodiert.

HTTP-Äquivalent

CamelCase-Feldnamen im SDK werden im eigentlichen HTTP-Request zu snake_case (zum Beispiel referenceDate → reference_date). Der folgende Body ist das, was POST /v1/systemone für dieselbe Aufgabe akzeptiert:

{
  "model": "clairic",
  "state": "INVOICE INV-2291\nIssued: 2026-09-02, net 30\nTotal due: 1080.00",
  "reference_date": "2026-10-19",
  "fields": {
    "invoice_number": { "type": "text" },
    "total": { "type": "number", "decimals": 2 }
  }
}

Siehe den Extraktionsvertrag der API für Authentifizierung, Idempotenz (ein erneuter Versuch derselben Operation mit demselben Schlüssel erzeugt keine zweite Abbuchung, solange der Replay-Eintrag besteht) und Header. Extraktions-Credits werden einmal pro Anfrage nach der Eingabegröße berechnet, nicht mit der Feldanzahl multipliziert. Prüfen Sie die aktuelle Credit-Rate vor dem Versand.

Nächste Schritte

• SDK installieren und evaluate()
• Gehosteter SDK-Schnellstart
• Modell wählen
• API-Referenz