> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Assistant Reference
> Every configuration key the in-sheet AI Assistant in Nextedy POWERSHEET reads: the project context properties that enable it, the assistantConfig sheet key, and the action configuration schema with its defaults.
export const LastReviewed = ({date}) => {
if (!date) return null;
const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
timeZone: "UTC"
});
return
Last reviewed on {formatted}
;
};
Configuration for the in-sheet **AI Assistant**, in three layers: project context properties that decide whether the button exists, one sheet configuration key that points at an action configuration, and the action configuration itself.
For the task-oriented walkthrough, see [Configure the AI Assistant](/powersheet/guides/administration/configure-the-ai-assistant).
## Project context properties
Set in the project's `com.polarion.context.properties`. All are booleans and all default to `true`.
| Property | Type | Default | Description |
| ----------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nextedy.powersheet.aiAssistant` | boolean | `true` | When `false`, removes the AI Assistant button from every sheet in the project. |
| `nextedy.powersheet.promotions` | boolean | `true` | Whenever the availability status is not `ok` -- the plugin is unlicensed, unreachable, or has no model key -- the disabled button and its invitation tooltip appear only while this is `true`. Setting it to `false` hides the button in all of those cases. |
| `nextedy.powersheet.adminAssistant` | boolean | `true` | Read by the configuration editor rather than by the sheet. Governs the [Admin AI Assistant](/powersheet/concepts/admin-ai-assistant). |
`nextedy.powersheet.aiAssistant` and `nextedy.powersheet.promotions` are read from the project configuration and returned to the client together with the sheet configuration JSON.
## Sheet configuration key
| Key | Type | Default | Description |
| ----------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assistantConfig` | string | *(unset)* | Names the Nextedy AI action configuration the sheet loads its actions from. While unset, the AI Assistant button and the **Edit AI Actions** document menu entry are both disabled. |
```yaml theme={null}
assistantConfig: requirements-assistant
```
## Availability statuses
Powersheet probes the Nextedy AI plugin's health endpoint for the current project and resolves one of three statuses. The toolbar button is clickable only when the status is `ok` **and** at least one AI action is defined for the sheet.
| Status | Resolved when | Tooltip on the disabled button |
| -------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ok` | The plugin is installed and licensed, and a model key is configured | *AI Assistant* (button enabled) |
| `unauthorized` | The plugin is installed but answered with HTTP 401 -- the Nextedy AI license is invalid | *AI Assistant — your Nextedy AI license is invalid. Contact your administrator.* |
| `unavailable` | The plugin is not installed or could not be reached, **or** no model key is configured | *This could be your Powersheet AI Assistant, helping you fill sheets faster by surfacing relevant items and justification. Want to see it in action? Contact us.* (a promotional message, not an error) |
When the status is `ok` but the sheet defines no actions, the tooltip reads *AI Assistant — configure AI actions for this powersheet to enable it.*
## Action configuration
An action configuration is a YAML file in the project's own repository at `.polarion/nextedy/ai/.yaml`, where `` is the value of `assistantConfig`. It holds a `globals` block and an `actions` block.
`actions` is a **map keyed by action id** -- the key identifies the action in the request the sheet sends, and is not repeated inside the action body. Each action supports the following keys.
| Key | Type | Default | Description |
| ------------------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | string | -- | The name shown in the assistant's action list. |
| `message` | string | -- | The instruction the action sends to the model. |
| `contextSources.row.fields` | map of string to string | -- | Fields of the selected row sent as context, as a map of field name to label. |
| `contextSources.project.fields` | map of string to string | -- | Fields of the project sent as context, as a map of field name to label. |
| `discover.search.maxCandidates` | number | `100` | How many candidates the search may return. |
| `discover.search.type` | string | derived | Polarion work item types to search, comma- or space-separated. When absent, the types are derived from the entity type bound to the column named by `apply.field`. |
| `discover.search.query` | string | *(none)* | An extra Lucene clause appended to the candidate query. |
| `discover.keywordPrompt` | string | -- | Instructs the model how to derive search keywords. Supports `${globals.}`. |
| `discover.rankPrompt` | string | -- | Instructs the model how to rank the candidates. Supports `${globals.}`. |
| `output.limit` | number | -- | Passed to the model as *Maximum number of items to select*. |
| `output.sortBy` | string | -- | Passed to the model as *Sort candidates by*. |
| `apply.field` | string | -- | The **column binding** an accepted recommendation is written to -- matched against the sheet's column bindings, so it is a binding expression such as `systemRequirements.systemRequirement`, not a bare field name. This is also the column the action's Polarion types are derived from and whose candidate filter constrains the result. |
**`apply.field` is what binds an action to a column**
An action configuration may also carry a `scope.columns` list, but nothing in Powersheet reads it -- the column an action searches, filters and writes against is resolved from `apply.field` throughout. Setting `scope.columns` has no effect. The same applies to `contextSources.document.fields` and `contextSources.user.fields`: both are accepted by the schema but neither is sent as context. Only `row` and `project` reach the model.
### Globals interpolation
`${globals.}` references inside `discover.keywordPrompt` and `discover.rankPrompt` are replaced from the configuration's `globals` block before the prompt is sent. The `globals` block is a flat map of string values whose key names you choose; a reference to a key the block does not define resolves to an empty string.
Write a phrase once in `globals` and refer to it as `${globals.}` from every prompt that needs it, rather than repeating it in each action.
### Candidate query
The query sent to Polarion is built as:
```
type:() AND project.id:""
```
with `discover.search.query` appended when present. `` comes from `discover.search.type`, or is derived from the entity type bound to the `apply.field` column when that key is absent. When neither resolves any type, the `type:` clause is omitted and the query is just `project.id:""`.
Whatever the model returns is re-checked against the **`apply.field` column's own candidate filter**, and any recommendation falling outside it is dropped. When every recommendation is dropped, the assistant reports *"No suggestions match this column’s allowed values."*
## Applying a recommendation
| Column cardinality | Effect | Undo stack entry |
| ------------------------- | ------------------------------------- | ----------------- |
| Many-to-many, one-to-many | Adds a row and links it | **Changed link** |
| Scalar reference | Sets the reference on the current row | **Set reference** |
The linked child row is inserted under **every rendered instance of the parent the action ran against** -- deduplicated by upstream id -- not only the one instance in view. This applies to every cardinality. Editing a link cell by hand is undoable through the same **Changed link** entry.
## Conversation storage
| Aspect | Value |
| -------------- | --------------------------------------------------------- |
| Scope | Per project and per document |
| Storage key | `ai-conversation-id::` |
| Refine context | Truncated to 4000 characters |
| Reset | The **New conversation** action in the window's title bar |
## See Also
* [AI Assistant](/powersheet/concepts/ai-assistant) -- what an action is and how a proposal is constrained
* [Configure the AI Assistant](/powersheet/guides/administration/configure-the-ai-assistant) -- setting these keys in practice
* [Use the AI Assistant](/powersheet/guides/save-operations/use-the-ai-assistant) -- the end-user task
* [Sheet Configuration Reference](/powersheet/reference/sheet-config/index) -- the rest of the sheet configuration schema