The AI narrative and insights layer

API reference › The AI narrative and insights layer

All 13 pages Everything on one page → Developer guide →

The AI narrative / insights layer

modules/ai is an opt-in layer that produces a short, plain-language narrative of the grid's computed figures - a per-KPI / per-chart / per-column “Explain”, or an insights panel over the current (filtered) view. It is a separate bundle that adds no weight to a page that does not load it, changes nothing in grid core, and pulls in no dependency. The grid makes no AI call of its own: createAI never imports a provider SDK, never reads a key, and never makes a network request. It calls one async callback you supply, ask() - your model, your key, your privacy decision - exactly the philosophy of the data adapters, where auth and transport are always the caller's.

import { createAI } from '@toclocoinc/lattice-grid/modules/ai';

const ai = createAI(grid, {
  ask: async ({ system, messages, tools, schema, signal }) => {
    const r = await myProvider.chat({ system, messages, tools, signal });
    return { text: r.text, toolCalls: r.toolCalls };   // or a bare string
  },
  maxRows: 50,                 // cap what any tool result carries to ask()
  redact: ['ssn', 'salary'],   // columns whose values never leave the browser
});

ai.insights(document.querySelector('#insights'));                 // the panel
const { text, flagged } = await ai.explain({ kind: 'column', colId: 'amount' });

Grounded, and reconciled. Where your provider offers tool-use, the model is given a curated read-only tool set (getSchema, getProfile, getStatistics, getForecast, runQuery) and our engine computes what it asks for; where it does not, the module builds a facts packet from the grid's computed results (grid.statistics, the profile, forecasts, view counts) and passes it in the prompt. Either way, every figure in the narrative is reconciled against the values the engine produced this render - an ungrounded number is stripped before the user sees it. The prompt is constrained to narrate-only; the layer is read-only and never mutates data. redact and maxRows bound what the module hands ask(), and the module sends nothing itself. An ask() error surfaces a friendly message and the grid stays fully usable - AI is additive, never load-bearing.

createAI is complementary to grid.ai: grid.ai is the intent/plan skill layer (a question becomes a validated filter/sort plan you preview and apply); createAI is the narrative/insights consumer that explains figures. They can share one host ask() - pass none to createAI and it adopts the grid's configured ai.ask, running the facts-packet path over it.

enable gates only the three DOM-mounting convenience methods: 'narrative'/'insights' is what lets insights() mount, 'query'/'ask' is what lets askBar() mount (see §Ask-your-data), and 'actor' is what lets actorBar() mount (see §AI as a governed actor). All three are allowed when enable is omitted. The programmatic API - explain(), query(), propose(), facts(), riskSummary() and the rest of the controller - is never gated by enable and runs regardless of the allowlist: a host that wants no AI surface at all simply never calls these methods.

Grounded, with the reconciliation guard, executed

A mock ask() returns one grounded figure (the row count) and one invented one. The number-reconciliation guard strips the ungrounded figure and keeps the grounded one. Run headless on every build.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createAI } = await import('../packages/modules/ai/index.js');

const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'region' }, { field: 'amount', type: 'number' }],
  rows: [
    { id: 1, region: 'EMEA', amount: 100 },
    { id: 2, region: 'AMER', amount: 300 },
    { id: 3, region: 'APAC', amount: 200 },
  ],
});

// Your model, your key. The grid makes no network call - it awaits this.
// This mock returns one grounded figure (3 rows) and one invented one (900%).
const ask = async () => ({ text: 'There are 3 rows in view. Confidence 900%.' });

const ai = createAI(grid, { ask, tools: false });
const result = await ai.explain({ kind: 'view' });

const kept = result.text.includes('3 rows');      // grounded - survives
const stripped = !result.text.includes('900%');   // hallucinated - removed

ai.destroy();
grid.destroy();
return `${result.flagged.length} flagged | ${kept} kept | ${stripped} stripped`;

Board / Gantt risk summary (modules/ai)

A project manager wants one line: “3 tasks at risk on the critical path, SPI 0.67, 2 SLA breaches.” ai.riskSummary(…) (and the { kind: 'risk' } target of explain) produces exactly that, grounded on figures the separate optional modules have already computed: gantt.earnedValue() for SPI/CPI and the schedule/cost variances, gantt.schedule for the critical path and the tasks at risk on it, and board.sla for the SLA breach and warning counts. Every figure runs through the same number-reconciliation guard as the rest of the narrative - an ungrounded figure is stripped before the user sees it.

The AI bundle imports neither the Gantt nor the Kanban module. You pass the module instances (or their already-computed outputs) on the target, and the layer reads them duck-typed - so a page that loads the AI module without those bundles carries none of their weight. buildRiskFacts(target, opts) is exported to build (and preview) the exact grounded facts a risk summary would use, without calling ask(). Redaction: a risk summary carries aggregates only by default - counts and the EVM indices/variances; it withholds task names and card contents. includeTaskNames adds the at-risk task names (bounded by maxTasks) and includeCost adds the money figures (BAC/PV/EV/AC), each the host's explicit opt-in, reported back in meta.exposed.

const { buildRiskFacts } = await import('../packages/modules/ai/index.js');

// The public outputs a host already holds from the SEPARATE gantt / kanban
// modules. The AI bundle imports neither - it reads these duck-typed.
const earnedValue = { ok: true, project: { spi: 0.8, cpi: 0.9, sv: -1000, cv: -500 } };
const schedule = {
  ok: true,
  order: ['a', 'b', 'c'],
  critical: ['a', 'b', 'c'],                    // all three on the critical path
  tasks: new Map([
    ['a', { id: 'a', name: 'Design', percentComplete: 100, totalFloat: 0 }],
    ['b', { id: 'b', name: 'Build', percentComplete: 40, totalFloat: 0 }],
    ['c', { id: 'c', name: 'Ship', percentComplete: 0, totalFloat: -2 }],
  ]),
};
const breaches = [{ key: 'CARD-1' }, { key: 'CARD-2' }];   // from board.sla.breaches()

const { facts } = buildRiskFacts({ kind: 'risk', earnedValue, schedule, breaches });
const by = Object.fromEntries(facts.map((f) => [f.id, f]));

// Two incomplete tasks (Build, Ship) are on the critical path - at risk.
return `${by['risk.atRisk'].display} at risk | SPI ${by['risk.spi'].display} | ${by['risk.sla.breaches'].display} breaches`;

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The AI module

AIFact

A single computed figure a narrative is grounded on.

AITarget

AIFactsPacket

The facts packet a narrative grounds on.

AIRiskFacts

The risk facts a board / Gantt risk summary grounds on, from {@link buildRiskFacts}: the facts plus which module sources resolved and which opt-in exposures (task names, cost) were honoured.

AINarrative

The result of a narrative: reconciled prose plus what grounded and what did not.

AIConfig

AI module configuration.

AIApplyReport

The report from applying an ask-your-data query.

AIQueryResult

The result of an ask-your-data question: a validated, READ-ONLY query spec - never rows - that the host reviews before applying.

AIDiffEntry

One before/after change in a governed-actor proposal.

AIProposal

AIProposalReport

The report from applying a governed-actor proposal.

AINarrativeEvent

`narrative`: a narrative run finished and its result is in hand. The result {@link AI.explain} resolves to, copied with `type` added by the module's emitter - the same figures, already reconciled, so a handler that only wants to paint the text need not await the call itself.

AIQueryEvent

`query`: an ask-your-data question resolved into a validated, read-only query spec. The result {@link AI.query} resolves to, copied with `type` added. It fires whether or not the spec is safe (`ok`) and whether or not `autoApply` applied it - the apply happens before the event, so `applied` is already filled in when it did.

AIProposalEvent

`proposal`: the governed actor produced a reviewable set of edits. The result {@link AI.propose} resolves to, copied with `type` added. Nothing has been written: this is the point at which a host shows the diff and asks a human.

AIErrorEvent

`error`: a run failed, and the call that started it is rejecting. Raised for a missing `ask()` and for an `ask()` that threw, on all three runs. The grid is untouched either way. Exactly one of `target`, `question` and `instruction` is present - whichever run failed.

AIEventPayloads

What a handler receives, per AI event.

AI

An AI controller over a live grid. It explains the grid's computed figures (Play A), answers questions with validated read-only query specs (Play B), and PROPOSES governed edits a human approves and the grid's own gate applies (Play C). `grid.ai` (in core) is the complementary intent/plan skill layer this consumes.

Properties

Methods

Events