AI Fields

Seven field types compute their value with an LLM from one or more sourceFields. All share the base field properties and a common set of AI controls.

Common AI Properties

Most AI fields accept these shared properties (in addition to their type-specific ones):

How a value resolves, and how to tell

An AI field resolves in two tiers. A deterministic value is computed locally and stored straight away, so the record is never left blank; a background refinement then replaces it with the model's answer.

When the refinement never lands, the locally computed value stays. It is plausible, well-formed content that reads exactly like a model result — so on its own, a value gives no clue which tier produced it. That is why every AI value carries a refinement status, and why the grid and the record drawer mark the two states that are not settled:

A settled value is deliberately left unmarked. Marking every value would teach readers to ignore the marker, and a hand-edited value is the reader's own — it needs no warning.

Editing an unrefined value by hand is the supported way out: the edit is kept, and a later refinement will not overwrite it.

Any write that supplies the column with an explicit value records skipped and clears the recorded reason, so the marker goes with it. A write that leaves the column alone leaves its status untouched. The field keeps a status of skipped rather than losing its entry, so a value someone wrote by hand stays distinguishable from one that was never computed at all.

computeOn decides when a field recomputes — ai-generate, ai-summary and ai-sentiment accept create (the default), update, or both; the other four always compute on create — but it has no bearing on this. An edit is respected whatever the setting.

Reading the status over the API

Records from a table with AI fields carry an _aiCompute block alongside fields, keyed by field name:

{
  "id": "42",
  "fields": { "summary": "Coastal ecosystems face accelerating change." },
  "_aiCompute": {
    "summary": { "status": "failed", "error": "provider unavailable" }
  }
}

status is one of pending, refined, failed or skipped; error is present only for failed. The block is omitted entirely for a table that declares no AI field, and for a record that has no status yet — it is never sent as an empty object, so a table that uses no AI costs nothing to read.

ai-generate

Generates free-form text from a prompt template.

- id: 1
  name: marketing_copy
  type: ai-generate
  sourceFields: [product_name, features]
  prompt: 'Write a compelling 2-paragraph marketing description for {{product_name}}. Key features: {{features}}.'

ai-summary

Summarizes the source fields. Uses a default "Summarize the following" prompt when prompt is omitted.

- { id: 2, name: ticket_summary, type: ai-summary, sourceFields: [body, thread] }

ai-categorize

Classifies the source into exactly one of a fixed category list.

- {
    id: 3,
    name: ticket_category,
    type: ai-categorize,
    sourceFields: [subject, body],
    categories: [billing, technical, account, general],
  }

ai-extract

Extracts structured data described by a JSON Schema. Supports nested objects and arrays.

- id: 4
  name: invoice_data
  type: ai-extract
  sourceFields: [raw_text]
  schema:
    type: object
    properties:
      vendor_name: { type: string, description: Name of the vendor }
      total_amount: { type: number, description: Total amount due }

ai-sentiment

Analyzes sentiment of the source text. prompt can adjust the focus (e.g. urgency, satisfaction).

- { id: 5, name: review_sentiment, type: ai-sentiment, sourceFields: [review_text] }

ai-tag

Assigns multiple tags from a predefined allow-list.

- {
    id: 6,
    name: article_tags,
    type: ai-tag,
    sourceFields: [title, body],
    tags: [technology, business, science, health, politics],
    maxTags: 3,
  }

ai-translate

Translates one source field into a target language.

- {
    id: 7,
    name: description_fr,
    type: ai-translate,
    sourceFields: [description],
    targetLanguage: fr,
  }