Table kit command
table.ai.apply
Write an AI field's results
Writes what the host's model generated (text, images or errors per record) into an AI field.
- Kit
- Table 0.4.0 (.ktable)
- Changes the document
- yes
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
action | string | no | The AI action (summarize, translate, extract, improve, customize, classify, text_generation, image_generation, image_customization); when given, it must be the field's own. |
asOrigin | string | no | system:<name> writes as a host feature, outside the undo history. Agents leave it out. |
config | object | no | Overrides of the field's AI configuration for this run. |
fieldId | integer | string | yes | The AI field's id. |
recordId | integer | string | no | One record to run on. |
results | object[] | yes | What the host generated, one entry per record. |
tableId | integer | string | yes | The table's id. |
Call through table_run
text
table_run {
"path": "<file>.ktable",
"steps": [{ "command": "table.ai.apply", "params": { "tableId": <integer | string>, "fieldId": <integer | string>, "results": <object[]> } }]
}The required parameters, with placeholders for their types: not a tested example. Optional: action, asOrigin, config, recordId. table_run answers the step’s result in completed[i].result.
Result
| Name | Type | Required | Description |
|---|---|---|---|
change | object | null | no | What the call changed, or null. |
error | object | no | Why the call failed (A18); the file is as it was. |
result | object | no | What was written: one record's `record`, `field` and `state`, or a batch's `items` and counts. |
Result JSON Schema
json
{
"additionalProperties": false,
"description": "The request's own answer is in `result`, beside `change`: what the call changed in the document (null when nothing changed). A failed call answers `error` instead (A18).",
"properties": {
"change": {
"description": "What the call changed, or null.",
"oneOf": [
{
"additionalProperties": false,
"description": "What one projection changed in the relational tables, by integer id. Every list is sorted and\nholds no repeats.",
"properties": {
"dashboards": {
"description": "A dashboard, or the base's list of them, changed.",
"type": "boolean"
},
"documentId": {
"type": "string"
},
"origin": {
"description": "Who wrote it: kind:principal, or a system origin's label.",
"type": "string"
},
"recordsDeleted": {
"description": "[tableId, rowKey] pairs.",
"items": {
"items": {},
"type": "array"
},
"type": "array"
},
"recordsReordered": {
"description": "Tables whose records' positions changed.",
"items": {
"type": "integer"
},
"type": "array"
},
"recordsUpserted": {
"description": "[tableId, rowKey] pairs.",
"items": {
"items": {},
"type": "array"
},
"type": "array"
},
"schema": {
"description": "Tables whose fields were added, removed, updated, or reordered.",
"items": {
"type": "integer"
},
"type": "array"
},
"tables": {
"description": "Tables whose own row changed: created, deleted, renamed, moved, or given a new primary\nfield.",
"items": {
"type": "integer"
},
"type": "array"
},
"views": {
"description": "Views created, deleted, updated, or reordered, or whose column widths or visibility\nchanged.",
"items": {
"type": "integer"
},
"type": "array"
}
},
"required": [
"tables",
"schema",
"views",
"recordsReordered",
"dashboards"
],
"type": "object"
},
{
"type": "null"
}
]
},
"error": {
"additionalProperties": false,
"description": "Why the call failed (A18); the file is as it was.",
"properties": {
"code": {
"enum": [
"invalid-params",
"invalid-op",
"invalid-value",
"not-found",
"read-only",
"unknown-command",
"command-failed",
"not-open",
"draft-required",
"not-allowed",
"unsupported",
"unavailable",
"failed"
],
"type": "string"
},
"index": {
"description": "The failing step or operation.",
"type": "integer"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"result": {
"additionalProperties": true,
"description": "What was written: one record's `record`, `field` and `state`, or a batch's `items` and counts.",
"properties": {
"accepted": {
"description": "Results taken (a batch).",
"type": "integer"
},
"completed": {
"description": "Records written.",
"type": "integer"
},
"errors": {
"items": {
"additionalProperties": true,
"description": "A result that failed.",
"properties": {
"message": {
"description": "Why.",
"type": "string"
},
"record_id": {
"description": "The record's id.",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"failed": {
"description": "Results that failed.",
"type": "integer"
},
"field": {
"additionalProperties": true,
"description": "A field (column).",
"properties": {
"ai_prompt": {
"description": "A legacy AI prompt.",
"type": "string"
},
"created_at": {
"description": "When it was created, in Unix milliseconds.",
"type": "integer"
},
"document_id": {
"description": "Always 1: the document's id.",
"type": "integer"
},
"formula": {
"description": "A formula field's expression.",
"type": "string"
},
"id": {
"description": "The field's local projection address (fieldId).",
"type": "integer"
},
"is_primary": {
"description": "It names the record.",
"type": "boolean"
},
"meta": {
"additionalProperties": true,
"description": "Metadata the host keeps with the field.",
"type": "object"
},
"name": {
"description": "The key of its values in a record's `values`.",
"type": "string"
},
"options": {
"additionalProperties": true,
"description": "The settings its type reads (choices, target_table_id, …).",
"type": "object"
},
"order": {
"description": "Its position among the table's fields, from 1.",
"type": "integer"
},
"readonly": {
"description": "Values are not written by hand (formula and AI fields).",
"type": "boolean"
},
"required": {
"description": "A record needs a value.",
"type": "boolean"
},
"table_id": {
"description": "The table's id.",
"type": "integer"
},
"title": {
"description": "The title people see.",
"type": "string"
},
"tool_id": {
"description": "The stable UUID accepted by fieldId and used by receipts and conflicts.",
"type": "string"
},
"type": {
"description": "The field type.",
"enum": [
"text",
"long_text",
"number",
"date",
"datetime",
"single_select",
"multi_select",
"checkbox",
"url",
"attachment",
"document_link",
"formula",
"ai",
"rating",
"user",
"link_to_record",
"lookup",
"rollup",
"button",
"created_time",
"last_modified_time",
"created_by",
"last_modified_by",
"auto_number"
],
"type": "string"
},
"unique": {
"description": "Values must differ between records.",
"type": "boolean"
},
"updated_at": {
"description": "When it last changed, in Unix milliseconds.",
"type": "integer"
},
"user_id": {
"description": "Always 0: the document's own user.",
"type": "integer"
}
},
"type": "object"
},
"items": {
"items": {
"additionalProperties": true,
"description": "A record written.",
"properties": {
"record": {
"additionalProperties": true,
"description": "A record (row).",
"properties": {
"created_at": {
"description": "When it was created, in Unix milliseconds.",
"type": "integer"
},
"document_id": {
"description": "Always 1: the document's id.",
"type": "integer"
},
"id": {
"description": "The record's local projection address (recordId).",
"type": "integer"
},
"order": {
"description": "Its position in the table, from 1.",
"type": "integer"
},
"row_key": {
"description": "The record's stable key, used by links, bulk commands and transact.",
"type": "string"
},
"table_id": {
"description": "The table's id.",
"type": "integer"
},
"tool_id": {
"description": "The stable UUID accepted by recordId and used by receipts and conflicts.",
"type": "string"
},
"updated_at": {
"description": "When it last changed, in Unix milliseconds.",
"type": "integer"
},
"user_id": {
"description": "Always 0: the document's own user.",
"type": "integer"
},
"values": {
"additionalProperties": true,
"description": "Its values, keyed by field name; a missing key is an empty value.",
"type": "object"
}
},
"type": "object"
},
"state": {
"additionalProperties": true,
"description": "The AI cell's run state.",
"properties": {
"config_hash": {
"description": "A hash of the field's AI configuration.",
"type": "string"
},
"error": {
"description": "Empty, or why it failed.",
"type": "string"
},
"model_id": {
"description": "Always 0.",
"type": "integer"
},
"source_hash": {
"description": "A hash of what the model read.",
"type": "string"
},
"status": {
"description": "done.",
"type": "string"
},
"updated_at": {
"description": "When it was written, in Unix milliseconds.",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
},
"type": "array"
},
"limit": {
"description": "The most records one batch takes.",
"type": "integer"
},
"record": {
"additionalProperties": true,
"description": "A record (row).",
"properties": {
"created_at": {
"description": "When it was created, in Unix milliseconds.",
"type": "integer"
},
"document_id": {
"description": "Always 1: the document's id.",
"type": "integer"
},
"id": {
"description": "The record's local projection address (recordId).",
"type": "integer"
},
"order": {
"description": "Its position in the table, from 1.",
"type": "integer"
},
"row_key": {
"description": "The record's stable key, used by links, bulk commands and transact.",
"type": "string"
},
"table_id": {
"description": "The table's id.",
"type": "integer"
},
"tool_id": {
"description": "The stable UUID accepted by recordId and used by receipts and conflicts.",
"type": "string"
},
"updated_at": {
"description": "When it last changed, in Unix milliseconds.",
"type": "integer"
},
"user_id": {
"description": "Always 0: the document's own user.",
"type": "integer"
},
"values": {
"additionalProperties": true,
"description": "Its values, keyed by field name; a missing key is an empty value.",
"type": "object"
}
},
"type": "object"
},
"state": {
"additionalProperties": true,
"description": "The AI cell's run state.",
"properties": {
"config_hash": {
"description": "A hash of the field's AI configuration.",
"type": "string"
},
"error": {
"description": "Empty, or why it failed.",
"type": "string"
},
"model_id": {
"description": "Always 0.",
"type": "integer"
},
"source_hash": {
"description": "A hash of what the model read.",
"type": "string"
},
"status": {
"description": "done.",
"type": "string"
},
"updated_at": {
"description": "When it was written, in Unix milliseconds.",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}Parameter schema
json
{
"additionalProperties": false,
"properties": {
"action": {
"description": "The AI action (summarize, translate, extract, improve, customize, classify, text_generation, image_generation, image_customization); when given, it must be the field's own.",
"type": "string"
},
"asOrigin": {
"description": "system:<name> writes as a host feature, outside the undo history. Agents leave it out.",
"type": "string"
},
"config": {
"additionalProperties": true,
"description": "Overrides of the field's AI configuration for this run.",
"type": "object"
},
"fieldId": {
"description": "The AI field's id.",
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"x-khp-types": [
"Field"
]
},
"recordId": {
"description": "One record to run on.",
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"x-khp-types": [
"Record"
]
},
"results": {
"description": "What the host generated, one entry per record.",
"items": {
"additionalProperties": true,
"properties": {
"error": {
"description": "Why generation failed for this record.",
"type": "string"
},
"image": {
"description": "A generated image."
},
"images": {
"items": {},
"type": "array"
},
"recordId": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"x-khp-role": "object",
"x-khp-types": [
"Record"
]
},
"text": {
"type": "string"
}
},
"required": [
"recordId"
],
"type": "object"
},
"type": "array"
},
"tableId": {
"description": "The table's id.",
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"x-khp-types": [
"Table"
]
}
},
"required": [
"tableId",
"fieldId",
"results"
],
"type": "object"
}Generated from kition-sdk packages/script/kits/table.ts and the kit itself (kition-table@ee73209). As data: commands.jsonl.