> ## 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 > How the in-sheet AI Assistant works in Nextedy POWERSHEET: configured actions that search Polarion for candidate work items, rank them against the row you are on, filter them through the column's own allowed values, and apply the ones you accept as reversible links. export const LastReviewed = ({date, state}) => { if (!date) return null; const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" }); const label = state === "reviewed" ? `Last reviewed and confirmed up to date on ${formatted}` : `Last updated on ${formatted}`; return

{label}

; }; The **AI Assistant** is a chat window inside a Powersheet document, opened from the sparkle button in the sheet toolbar. Unlike a general-purpose chatbot, it runs **actions an administrator has configured for that sheet**: an action searches Polarion for candidate work items, ranks them against the row you have selected, and proposes a shortlist you can apply into the sheet as links. This page explains the model behind that — what an action is, how a proposal is constrained before you ever see it, what "apply" writes, and when the assistant is available at all. **Two different assistants, and this is not the other one** Powersheet ships with a second, unrelated assistant: the [Admin AI Assistant](/powersheet/concepts/admin-ai-assistant), a documentation-grounded chat inside the **configuration editor**. That one answers questions about Powersheet configuration and can never change anything. The assistant on this page lives inside the **sheet**, requires a valid Nextedy AI license, and does write to Polarion when you accept a suggestion. They have separate availability signals and separate configuration. ## Actions, not free-form chat The assistant's unit of work is an **action**. An administrator defines a set of actions in a Nextedy AI action configuration and names that configuration on the sheet through the `assistantConfig` sheet configuration key; the assistant loads the actions from it when it opens. With an empty conversation the window lists those actions, and choosing one runs it against the row currently selected in the sheet. An action bundles everything the model needs for one job: | Part of an action | What it decides | | - | - | | `apply.field` | The column the action is bound to — where an accepted recommendation is written, and the column whose entity type and candidate filter constrain it | | `contextSources` | Which row and project fields are sent as context for the current row | | `discover.search` | How candidates are found in Polarion — work item types, an extra query, and how many candidates to consider | | `discover.keywordPrompt` / `discover.rankPrompt` | How candidates are searched for and then ranked | | `output.limit` / `output.sortBy` | How many items to select, and in what order | The full key-by-key list is in the [AI Assistant reference](/powersheet/reference/ai-assistant). Because an action is configuration rather than a prompt typed by the reader, the same question asked by two engineers on the same sheet runs the same search against the same work item types with the same ranking instructions. ## How a suggestion is constrained A recommendation passes three narrowing stages before it reaches you, and only the last one is visible. Candidates are fetched from Polarion with a query built as `type:() AND project.id:""`, with anything in `discover.search.query` appended. When the action does not name `discover.search.type`, the work item types are derived from the entity type bound to the action's `apply.field` column — so an action writing into a column bound to system requirements searches system requirements without being told to. If no type resolves either way, the search falls back to the project alone. `discover.search.maxCandidates` caps how many candidates are considered, and defaults to 100 when the action omits it. The candidates, the context gathered through `contextSources`, and the action's ranking instructions go to the model together. `output.limit` reaches it as *Maximum number of items to select* and `output.sortBy` as *Sort candidates by*, so the shortlist's size and ordering are the administrator's decision rather than the model's. Each item comes back with a **justification** — one sentence on why it fits the row — which is shown under the item's id and title. Whatever the model returns is re-checked against the **`apply.field` column's own candidate filter**, and anything that falls outside it is dropped before it is offered. A column that only accepts hazards from one document will not be offered a requirement from another, however confidently the model ranked it. When every recommendation is filtered out, the assistant says so rather than showing an empty list. The constraints an administrator already expressed in the data model and the sheet configuration — allowed types, document scoping, picker filters — stay in force through this last stage. The assistant cannot propose something you could not have picked by hand. ## What "apply" writes Applying a recommendation is an ordinary sheet edit, not a privileged one. What it does depends on the cardinality of the column you are on: | Column | Applying a recommendation | Undo entry | | - | - | - | | Many-to-many or one-to-many | Adds a row and links it | **Changed link** | | Scalar reference | Sets the reference on the current row | **Set reference** | Both land in the sheet's change buffer like any other edit, so they are reversible from the undo stack and are only written to Polarion when you save. [Working sessions](/powersheet/concepts/working-sessions) covers that buffer and the explicit-save model in full. **The new row appears under every rendered instance of the parent** The same parent can be rendered several times in a hierarchical sheet. When a recommendation is applied, the linked child row is inserted under **every rendered instance of that parent**, deduplicated by upstream id — not only the one the action happened to run against. The sheet therefore stays consistent, rather than showing the new link in one place and not another. ## Refining an answer As soon as an action has been run, a **Refine** bar appears above the message box, naming the action it will re-run. Refining re-runs that same action with fresh sheet data and the conversation so far, so a reviewer can steer it — "these are all from the wrong subsystem" — without re-picking the action and losing the thread. It is disabled while a response is still streaming. The conversation itself is kept **per project and per document**, so moving between documents does not carry one sheet's thread into another, and returning to a document brings its own thread back. The **New conversation** action in the window's title bar clears it. The conversation sent back to the model as refine context is truncated to 4000 characters, so a very long thread contributes only its most recent part. ## Availability The assistant's availability is a separate signal from the rest of Powersheet: when it is unavailable the button is disabled and everything else in the sheet keeps working. Powersheet probes the Nextedy AI plugin's health endpoint for the current project and resolves one of three statuses — **ok** (installed, licensed, and a model key configured), **unauthorized** (the plugin answered with HTTP 401, meaning the Nextedy AI license is not valid), or **unavailable** (the plugin is not installed or could not be reached, or no model key is configured). The toolbar button is clickable only when the status is **ok** *and* at least one AI action is defined for the sheet. Otherwise the sparkle icon is greyed out and hovering it explains why: | Situation | Tooltip | | - | - | | Ready | *AI Assistant* | | Nextedy AI license is not valid | *AI Assistant — your Nextedy AI license is invalid. Contact your administrator.* | | No AI actions configured for the sheet | *AI Assistant — configure AI actions for this powersheet to enable it.* | | Nextedy AI plugin unreachable, not installed, or without a model key | *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.* | That last tooltip is a promotional message rather than an error report, so a project with no Nextedy AI plugin shows an invitation instead of a failure. Two project context properties control whether it is shown at all — `nextedy.powersheet.aiAssistant` removes the button from every sheet in the project, and `nextedy.powersheet.promotions` suppresses the disabled button whenever the status is anything other than **ok**. Both are covered in [Configure the AI Assistant](/powersheet/guides/administration/configure-the-ai-assistant). ## Related Pages Run an action against a row and apply what it proposes. Enable it for a project, point a sheet at an action configuration, and edit its actions. Every action configuration key and project context property, with defaults. The cardinalities that decide what applying a recommendation writes. ## See Also * [Create a Link](/powersheet/guides/save-operations/create-link) — the manual route the assistant automates * [Admin AI Assistant](/powersheet/concepts/admin-ai-assistant) — the other, non-mutating assistant, in the configuration editor * [Working Sessions](/powersheet/concepts/working-sessions) — the change buffer and undo stack an applied recommendation lands in This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.