# AI Fields

Seven field types compute their value with an LLM from one or more `sourceFields`. All share the [base field properties](/en/docs/tables-overview#base-field-properties) and a common set of AI controls.

| Type            | Produces                                                  |
| --------------- | --------------------------------------------------------- |
| `ai-generate`   | Free-form generated text from a prompt template.          |
| `ai-summary`    | A summary of the source fields.                           |
| `ai-categorize` | A single category chosen from a predefined list.          |
| `ai-extract`    | Structured data matching a JSON Schema.                   |
| `ai-sentiment`  | Sentiment analysis of the source text.                    |
| `ai-tag`        | Multiple tags chosen from an allow-list.                  |
| `ai-translate`  | A translation of one source field into a target language. |

## Common AI Properties

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

| Property       | Description                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `sourceFields` | **Required.** Field names used as input context. At least one (exactly one for `ai-translate`).                                    |
| `prompt`       | Custom prompt to guide the AI. `ai-generate` uses a `{{fieldName}}` template; others fall back to a sensible default when omitted. |
| `systemPrompt` | System prompt setting the AI persona and context.                                                                                  |
| `model`        | AI model override (e.g. `gpt-4o`, `claude-sonnet`). Non-empty string.                                                              |
| `temperature`  | Output creativity, `0` to `1`.                                                                                                     |

## `ai-generate`

Generates free-form text from a prompt template.

| Property | Description                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------ |
| `prompt` | Prompt template with `{{fieldName}}` variable substitution. _(Recommended for generate fields.)_ |

```yaml
- 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.

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

## `ai-categorize`

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

| Property     | Description                                                                            |
| ------------ | -------------------------------------------------------------------------------------- |
| `categories` | **Required.** Predefined categories the AI must choose from. Minimum 2, no duplicates. |

```yaml
- {
    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.

| Property | Description                                                                      |
| -------- | -------------------------------------------------------------------------------- |
| `schema` | **Required.** JSON Schema object describing the structure of the extracted data. |

```yaml
- 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).

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

## `ai-tag`

Assigns multiple tags from a predefined allow-list.

| Property  | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `tags`    | **Required.** Allowed tags the AI may assign. Minimum 2, no duplicates.     |
| `maxTags` | Maximum number of tags to assign (positive integer). No limit when omitted. |

```yaml
- {
    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.

| Property         | Description                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `sourceFields`   | **Required.** Exactly **one** field name.                                                           |
| `targetLanguage` | **Required.** ISO 639-1 language code, optionally region-suffixed (e.g. `fr`, `es`, `ja`, `zh-CN`). |
| `prompt`         | Custom prompt to control translation tone, formality, and style.                                    |

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

:::callout
**AI provider routing.** AI fields route through Sovrium's provider-precedence resolver (env-controlled, local-first by default). The optional `model` property overrides the default model for that field. The connecting role still gates execution wherever the table is exposed via the MCP server.
:::