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

Parameters of table.ai.apply
NameTypeRequiredDescription
actionstringnoThe AI action (summarize, translate, extract, improve, customize, classify, text_generation, image_generation, image_customization); when given, it must be the field's own.
asOriginstringnosystem:<name> writes as a host feature, outside the undo history. Agents leave it out.
configobjectnoOverrides of the field's AI configuration for this run.
fieldIdinteger | stringyesThe AI field's id.
recordIdinteger | stringnoOne record to run on.
resultsobject[]yesWhat the host generated, one entry per record.
tableIdinteger | stringyesThe 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

Result of table.ai.apply
NameTypeRequiredDescription
changeobject | nullnoWhat the call changed, or null.
errorobjectnoWhy the call failed (A18); the file is as it was.
resultobjectnoWhat 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.