Examples

// app/api/jev/route.ts
import { createJevHandler } from "@specstory/ai-data-grid/server";
import { getSession } from "@/lib/auth"; // your own authentication

export const POST = createJevHandler({
    apiKey: process.env.TYPESAFE_API_KEY ?? "",
    // Only signed-in users may spend the key.
    authorize: async request => (await getSession(request)) !== undefined,
});

// contacts-grid.tsx
"use client";
import * as React from "react";
import {
    DataEditor,
    type AIFillConfig,
    type EditableGridCell,
    type GridCell,
    GridCellKind,
    type GridColumn,
    type Item,
} from "@specstory/ai-data-grid";
import "@specstory/ai-data-grid/dist/index.css";

interface Contact {
    id: string;
    name: string;
    title: string;
    notes: string;
    persona: string;
}

const columns: GridColumn[] = [
    { id: "name", title: "Name", width: 160 },
    { id: "title", title: "Title", width: 200 },
    { id: "notes", title: "Notes", width: 320 },
    { id: "persona", title: "Persona", width: 220 },
];

const fields = ["name", "title", "notes", "persona"] as const;

export function ContactsGrid({ initial }: { initial: Contact[] }) {
    const [contacts, setContacts] = React.useState(initial);

    const getCellContent = React.useCallback(
        ([col, row]: Item): GridCell => {
            const value = contacts[row][fields[col]];
            return { kind: GridCellKind.Text, data: value, displayData: value, allowOverlay: true };
        },
        [contacts]
    );

    // Every write, typed by a user or accepted from AI Fill, arrives here.
    const onCellEdited = React.useCallback(([col, row]: Item, cell: EditableGridCell) => {
        if (cell.kind !== GridCellKind.Text) return;
        setContacts(previous =>
            previous.map((contact, i) => (i === row ? { ...contact, [fields[col]]: cell.data } : contact))
        );
    }, []);

    const aiFill = React.useMemo<AIFillConfig>(
        () => ({
            connection: { mode: "endpoint", url: "/api/jev" },
            model: "jev-latest",
            rows: { getRowId: row => contacts[row].id },
            rowScope: () => ({ rows: "displayed", label: "contacts" }),
            columns: {
                persona: {
                    primitive: "choice",
                    instructions: "Which buyer persona best describes this contact?",
                    sources: ["title", "notes"],
                    options: {
                        champion: {
                            description: "Drives the purchase internally and advocates for it",
                            label: "Champion",
                        },
                        economic: { description: "Controls the budget and signs off on spend", label: "Economic buyer" },
                        technical: { description: "Evaluates the product's technical fit", label: "Technical evaluator" },
                        user: { description: "Uses the product day to day", label: "End user" },
                        none: { description: "None of these fit", label: "None of the above", outcome: "none" },
                    },
                    policy: {
                        show: { minProbability: 0.5 }, // below 0.5: withheld
                        ready: { minProbability: 0.8 }, // 0.5 to 0.8: review
                        autoApply: { minProbability: 0.95, options: { notIn: ["none"] } }, // only in "Fill and apply"
                    },
                    presentation: { showProbability: true, alternatives: { count: 3 } },
                },
            },
            onCommit: ({ commitId, source, edits }) => {
                // For example, record who accepted what, with the model that answered.
                console.info(commitId, source, edits.map(edit => [edit.rowId, edit.metadata.model]));
            },
            onError: error => console.warn(`AI Fill: ${error.kind}: ${error.message}`),
        }),
        [contacts]
    );

    return (
        <DataEditor
            aiFill={aiFill}
            columns={columns}
            rows={contacts.length}
            getCellContent={getCellContent}
            onCellEdited={onCellEdited}
            rowMarkers="number"
            width="100%"
            height={480}
        />
    );
}

const levels = [
    { description: "Individual contributor: no direct reports", label: "IC" },
    { description: "Manager: leads a team", label: "Manager" },
    { description: "Director: leads managers or a function", label: "Director" },
    { description: "Vice president or C-level: leads a division or the company", label: "Executive" },
];

const columns: AIFillConfig["columns"] = {
    seniority: {
        primitive: "score",
        instructions: "How senior is this contact?",
        sources: ["title"],
        levels,
        output: { store: "level-label", levelFrom: "nearest" },
        policy: { show: { minConfidence: 0.4 }, ready: { minConfidence: 0.7 } },
        presentation: { showConfidence: true, rubricBar: true },
    },
    // The same question, keeping the score itself in a number column.
    seniorityScore: {
        primitive: "score",
        instructions: "How senior is this contact?",
        sources: ["title"],
        levels,
        output: { store: "score", precision: 2 },
    },
};

const columns: AIFillConfig["columns"] = {
    ownsBudget: {
        primitive: "noul",
        instructions: "Does this contact own a budget?",
        criteria: { true: "Signs off on spend", false: "No spending authority" },
        sources: ["title", "notes"],
        output: {
            store: "boolean",
            bands: { falseAtOrBelow: 0.2, trueAtOrAbove: 0.8, between: "review" },
        },
        presentation: { probabilityBar: true },
    },
};

import { render } from "@testing-library/react";
import { createMockJev } from "@specstory/ai-data-grid/testing";

const jev = createMockJev({
    latencyMs: 0,
    rules: [
        {
            instructions: /buyer persona/,
            answer: {
                type: "choice",
                choice: "economic",
                probabilities: { champion: 0.03, economic: 0.91, technical: 0.03, user: 0.02, none: 0.01 },
                confidence: 0.84,
            },
        },
    ],
});

render(<DataEditor aiFill={{ ...aiFill, connection: jev.connection }} /* … */ />);