@gestaltbi/inference

The shape of it

import { profileFrame, listModels, recommend } from '@gestaltbi/inference';
import { StructureDirectory } from '@gestaltbi/stream';

// 1. describe the data — this is the entire payload
const profile = {
  ...profileFrame(rows, new StructureDirectory(structure)),
  modes: ['pivot', 'correlate', 'long'],   // what your host can actually render
  views: ['table', 'graph'],
};

// 2. let the user pick a model that can do the job
const models = (await listModels({ apiKey })).filter((m) => m.structuredOutputs);

// 3. ask, and keep what grounds
const suggestions = await recommend(profile, { apiKey, model: models[0].id });

Each suggestion names an analysis in your vocabulary — a mode, a view, the columns for each axis, the measure to fill it — so a host can turn one into a rendered view without interpreting prose.

The rows do not leave

profileFrame returns statistics, not records: what each column is for, how populated it is, how many distinct values a dimension has, the range of a measure, the period a date column covers. That is what gets sent — by recommend and by composeStory alike. There is no code path that puts a row in a request.

The single exception is sampleValues, which is off by default:

profileFrame(rows, directory, { sampleValues: true, maxSamples: 5 });

Turn it on and a few real values per dimension are included, which helps a model work out what a column means. It also means a customer list reaches a third party. disclosedValues(profile) returns exactly what would be sent, so a host can show someone what they are agreeing to before they agree.

Advice that teaches

A chart nobody knows how to read teaches nothing. A recommendation carries three pieces of writing that are deliberately not the same thing.

"Which product lines carry the margin?" — not "a pivot of margin by product line". And reading is written for someone who has never read a chart of that kind and has to decide something today: a long tail, a flat line, one bar carrying most of the total, two series drifting apart.

Nothing is taken on trust

A model asked to name columns will sometimes name plausible ones that are not there — revenue when the column is smartbi:calc:daily_revenue:sum. Acting on that renders an empty view and explains nothing, which reads as the product being broken.

So every suggestion is checked against the profile it was generated from: the columns exist, an axis is a dimension and not a measure, the column is not empty, the mode and view are ones the host offers.

const all = await recommend(profile, { apiKey, model, keepUngrounded: true });
all.filter((r) => !r.grounded).forEach((r) => console.log(r.title, r.problems));
// → "Margin by channel"  [ 'rows: no column "channel" in this dataset' ]

The default is to drop them. keepUngrounded shows the misses, which is the more honest thing to put in front of someone evaluating a model.

From analysis to report

A list of recommended charts is still a to-do list. composeStory turns one into the report an owner would otherwise have paid a consultant for.

const { story, problems } = await composeStory(profile, suggestions, {
  apiKey, model, chapters: 4, language: 'Italian',
});

story is a @gestaltbi/storybook Story — data, not markup — ready for resolveStory(story, rows).

The model writes the sentences; the data supplies the numbers

Every figure in the prose is a {{token}} the model declares and your host computes against the real frame. The model decides what to compute and never learns what it came to, so it cannot round, misremember or flatter a number it never saw. It is told to write sentences that stay true whichever way the value falls, and to put a check on any claim that matters so the data can contradict it.

Stories are grounded like recommendations, but by the chapter: dropping one bad figure would leave its {{token}} standing in a sentence with no number in it, which reads worse than the chapter being absent. So a chapter that reaches for a column this dataset does not have goes whole, and problems says which and why.

problems // → ['Margin — figure "m": no column "margin"']

Choosing a model

OpenRouter fails a request outright when a model cannot honour response_format — it does not quietly ignore it. So listModels reports structuredOutputs per model, and a picker should prefer those.

If a model refuses anyway, complete retries once without the schema and sets degraded, because a user who picked a model should get an answer rather than an error. Parsing stays defensive either way: JSON in a fenced block, JSON buried in prose, or a bare array all read the same, and something unusable returns an empty list rather than throwing.

Requests go straight to openrouter.ai/api/v1, so nothing sits between the user and the provider they are paying. Attribution headers — HTTP-Referer and X-Title, which affect OpenRouter's public rankings — are sent only when a host asks for them.