Configuration

The aiFill prop takes an AIFillConfig. This page lists every setting. Examples has complete configurations, and every type has TSDoc in the package.

import type { AIFillConfig } from "@specstory/ai-data-grid";

const aiFill: AIFillConfig = {
    connection: { mode: "endpoint", url: "/api/jev" },
    model: "jev-latest", // required, no hidden default
    rows: { getRowId: row => contacts[row].id }, // results are keyed by stable row id, never by position
    rowScope: () => ({ rows: "displayed", label: "filtered contacts" }),
    columns: {
        // keyed by GridColumn.id
        persona: {
            primitive: "choice",
            instructions: "Which buyer persona best describes this contact?",
            sources: ["company", "title"],
            options: {
                champion: { description: "Drives the purchase internally", label: "Champion" },
                economic: { description: "Controls the budget", label: "Economic buyer" },
                none: { description: "None of these fit", label: "None of the above", outcome: "none" },
            },
            policy: {
                show: { minProbability: 0.8 },
                ready: { minProbability: 0.95 },
                autoApply: { minProbability: 0.95 },
            },
        },
        seniority: {
            primitive: "score",
            instructions: "How senior is this contact?",
            sources: ["title"],
            levels: ["Individual contributor", "Manager", "Director", "Executive"],
            output: { store: "level-label" },
            policy: { show: { minConfidence: 0.7 } },
        },
        ownsBudget: {
            primitive: "noul",
            instructions: "Does this contact own a budget?",
            sources: ["title", "notes"],
            output: { store: "boolean", bands: { falseAtOrBelow: 0.2, trueAtOrAbove: 0.8, between: "review" } },
        },
    },
};

Grid settings

execution

A Retry-After or retry-after-ms of up to 60 seconds from the server is honored instead of the backoff.

Column settings

Every AI column has these:

The default row state is { [sourceId]: value } for each source column, in order: the text of text, URI, markdown and row-id cells (an empty one sends ""), the number of number cells, the boolean of boolean cells, the data of image and bubble cells, a drilldown's item texts, a custom cell's copyData, and null for a missing value, an empty number or boolean, and loading or protected cells.

Choice

• options: { [id]: { description, label?, value?, outcome? } }, 2 to 255 of them. The ids and descriptions are what Jev sees. label is what users see, and value is what is written (default label ?? id).
• outcome: "none" | "unknown" marks a semantic outcome, such as "none of the above" or "not enough information". It is an answer, not an error or a withheld result, and it writes nothing unless the option sets a value.
• presentation: { showProbability?, showConfidence?, alternatives?: { count, minProbability? } }: the probability and confidence shown next to a suggestion, and how many other options the inspector lists.

Score

• levels: the rubric, lowest first, 2 to 10 levels. A level is a string, or { description, label?, value? } where description is a string or an object such as { what, examples }.
• output.store: "score" (the score rounded to output.precision, default 2), "level" (the level index), "level-label", "level-value" (every level needs a value) or a function of the answer.
• output.levelFrom: "nearest" (the level nearest the score, half up; the default) or "most-probable" (the level with the highest probability, ties to the lower level).
• presentation: { showConfidence?, rubricBar? }.

Noul

• criteria?: { true?, false? }: what yes and no mean.
• output.store: "probability" (the default, rounded to precision), "boolean" or "label". The last two need bands: { falseAtOrBelow, trueAtOrAbove, between: "review" | "withhold" }; there are no default bands.
• output.labels: the true, false and uncertain labels. Default Yes, No and Uncertain.
• presentation: { probabilityBar? }.

The raw answer, the display text and the written value are three separate things. mapAIOutput returns answer, display and value (with hasValue), plus the semantic outcome.

Callbacks

A callback that throws doesn't stop AI Fill; the error is rethrown asynchronously so it still shows in the console.

Validation

AI Fill validates the configuration whenever the object changes. Each problem is reported once through onError as a configuration error and listed in api.getRunState().issues. A problem with a columnId disables that column; one without disables AI Fill for the grid. You can run the same check yourself, for example in a test:

import { validateAIFillConfig } from "@specstory/ai-data-grid";

const issues = validateAIFillConfig(aiFill, { columns }); // [{ path, message, columnId? }]

It reports, among others: a missing model or getRowId, AI columns that aren't grid columns, unknown sources, the wrong number of options or levels, overlapping or out-of-range thresholds, unknown option or level ids in a policy, a Noul boolean or label store without bands, a confidence gate on a Noul, and a direct-mode key in a browser without dangerouslyAllowBrowser. Messages never include the API key.