How to run an AI action
What this page is — the two places Orbit Papers offers AI on a document, what running one actually does, and what it costs.
What it is for — so the 23 capabilities are something you reach for deliberately, on the document in front of you, rather than a menu nobody opens.
The problem it solves — unclear costs and prerequisites mean people either never try the AI or spend credits on runs that return nothing useful.
Route: /org/papers/documents/<document>/ai, or AI Assistant on the document ·
Permission: Use AI drafting/extraction/Q&A for documents.
1. Two surfaces, the same capabilities
| Surface | Where | Use when |
|---|---|---|
| AI Assistant drawer | On the document, beside the fields | You are working on the document and want an answer without leaving it |
| AI workspace | The document's own AI page | You are reviewing rather than editing, and want room to read results |
The capabilities, the results and the cache are shared between them — a result generated in the drawer is the same result the workspace shows. They differ only in how much room you get to read it.
The four groups
| Group | Answers | Capabilities |
|---|---|---|
| Understand | What does this document say? | 7 |
| Negotiate | How good a deal is it, and what is still open? | 8 |
| Comply | Does it meet our rules and the law? | 7 |
| Transform | Turn its content into structured values | 1 |
The full list, with cost, inputs and what each writes, is in the AI capabilities reference.
2. Why you would use them
The economics of contract review are unforgiving: the cost of reading is paid every time, by whoever happens to be holding the document, and the value of having read it decays.
- They answer against the document in front of you. Reading a fifty-page agreement to answer one question is how review becomes a bottleneck. These answer the question directly, with the clause cited so you can check.
- A result is generated once and read many times. Because results are saved to the document (§5), the cost is paid once and the answer is available to everyone thereafter. That is where the saving actually comes from — not from any single run being fast.
- They make expertise available to whoever has the document. A reviewer who has never seen a lease gets the lease checklist, the retention statute and the fairness calibration applied to their first one.
- The ones that write turn analysis into tracked work. Extraction seeds the obligation register; the graph builds the knowledge graph. Those two convert reading into something the organisation can act on later (§6).
- They are cheap relative to what they catch. 450 credits against an uncapped indemnity, a double-applied tax, or a notice period shortened inside a reformat.
3. What you provide
Most capabilities are a single press. Four need something first, and the interface asks rather than offering a button that could only fail:
| Capability | Needs | Required? |
|---|---|---|
| Compromise draft | Both positions, typed in | Yes — it refuses without them |
| Redline grade | The specific counterparty redline to grade | Yes — suggestion_id or suggestion_text |
| Regional annexures | Jurisdictions | Only if the document names none itself |
| Smart fields | Definitions configured in Papers settings | Nothing at run time, but nothing runs without them |
Several more take an optional input that materially changes the answer — the perspective on Risk analysis, the audience on Redaction suggestions, the policy on Compliance & policy check. Leaving those blank gives you a usable default, not the best answer available.
Three are perspective-aware
Risk analysis, Shadow redline and Fairness / balance are cached per perspective — our side, the counterparty, or neutral.
The most useful thing risk analysis can tell you is often what the counterparty will object to. Because results are cached per perspective, both answers are kept — and switching perspective is a separate run at a separate charge, not a refresh of the same one.
4. Worked example — one document, four capabilities
A supplier's master services agreement arrives. Here is what a full first pass costs and returns.
| Step | Capability | Input | What it gave back |
|---|---|---|---|
| 1 | Fairness / balance | our side | 34 — heavily one-sided. This is the triage decision: worth a full review |
| 2 | Missing clauses | — | No limitation of liability, importance: high |
| 3 | Risk analysis | our side | Uncapped liability at clause 11, with the redline to ask for |
| 4 | Risk analysis | counterparty | Their objection list — the IP assignment at clause 14 |
Total: 1,800 credits, four runs, about six minutes.
What the reviewer walks away with. Not four reports — one negotiating position. Fairness said the document is worth arguing about; missing clauses and risk analysis agreed on what (the uncapped liability) and supplied the specific ask (mutual cap at 12 months' fees, carve-outs for confidentiality and IP); and the counterparty-perspective run named the trade — concede narrowing on clause 14 to win the cap on clause 11.
All four results are now saved on the document. The colleague who picks this up next week pays nothing to see them.
5. Results are kept with the document
A result belongs to the document, not to your session. Somebody opening the document tomorrow sees what was already run. That is deliberate: it makes the analysis part of the document's history, and it stops the same question being paid for repeatedly.
Reading a cached result is free. Only a re-run is charged.
The cache is keyed on this document's content, which is right for most capabilities and misleading for two:
- Cross-document consistency compares against related documents. If one of those changed, this document did not — so nothing invalidates the cache.
- Regulatory drift is a snapshot of the law on the day it ran, and the law moves without touching your document at all.
For those two, re-run on a schedule rather than trusting age.
6. What is applied, and what is not
The general rule is that nothing is applied to a document automatically. Not a clause, not a redline, not a translation, not a retention date. A legal artifact only changes when a person changes it — every AI result is a proposal you read first.
Two capabilities are exceptions, and they do not touch the document body either:
| Capability | Writes | Behaviour on re-run |
|---|---|---|
| Extract key terms | The obligation register — obligations tagged source: ai_extracted | Adds only what is new; deduped by description. Extracted obligations can be cancelled but never deleted |
| Entity & concept graph | The knowledge graph — this document's edges | Replaces this document's AI-derived edges rather than merging |
Neither alters a word of the document. But both change data the organisation then works from, so both are decisions rather than free actions.
7. The admin contract
Five things must be true before a capability appears, and all but the first fail silently.
| Must be true | Where | What happens if it is not |
|---|---|---|
| Your role holds Use AI drafting/extraction/Q&A for documents. | Role editor | No AI Assistant button at all |
The utility's global is_active switch is on | Orbit AI Flow → utilities | "This utility is currently disabled" |
| The utility is enabled for your organisation | /org/ai-utilities | The capability is absent from its group, with no error anywhere |
papers.ai_monthly_credit_cap is not reached | System Config | "monthly AI credit cap reached: n of n credits used this month". 0 means uncapped |
| The document has extractable text | The document | A scanned PDF analyses to nothing. Run OCR first |
This is the most common misconception about Papers AI, and it sends people to the wrong screen.
The type's AI Config tab governs auto-run only — which capabilities fire on submit, round or finalize. Manual runs are always available regardless of what the type configures. A capability missing from a group is a permission or a utility-enablement problem, never a type problem.
For a document whose confidentiality is confidential:
- Automatic runs are blocked entirely — default deny. A platform administrator must set the
System Config key
papers.ai_confidential_cloudto the literal valueallow. The block is silent to the user and appears only in the server log. - Manual runs are not blocked. Where a local model key is configured, the run is forced onto the
on-prem model and audited on the document timeline as
ai_local_routed; content never reaches a cloud API.
So a confidential document can return a result you pressed for, while its type's auto-run policy quietly does nothing.
8. Drafting AI is a different thing
The Drafting AI drawer on the authoring page writes: it drafts a body, suggests clauses, rewrites tone, translates, turns a transcript into a document, and proposes counter-proposals. It also carries a Human writing depth control.
The capabilities on this page analyse. The distinction matters because drafting output is meant to be edited and applied, while analysis is meant to be read.
Compromise draft sits on the drafting side despite appearing in the Negotiate group — it produces wording to paste, and it is reached from the Drafting AI drawer.
9. Don't confuse this with…
| Orbit AI Flow | Where utilities, prompts and models are administered. This is where they are used |
| Ask the repository | Answers across the whole corpus. These run against one document |
| AI configuration | Where auto-run is set per type. It never controls what is offered manually |
| Zonal extraction | Reads fixed positions on a scanned page. These read meaning |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| No AI Assistant button | Your role lacks Use AI drafting/extraction/Q&A for documents. |
| A capability is missing from a group | The utility is off for your organisation (§7). Not a document-type setting |
| A whole group is missing | Every capability in it is disabled. Transform has one member, so it vanishes entirely |
| A result looks stale | It is cached with the document. Re-run — and see the two special cases in §5 |
| A capability will not run on a press | It is one of the four that need an input first (§3) |
| Nothing ran on submit or finalize | Nothing is configured on the type, or the document is confidential and cloud AI is default-denied (§7) |
| Obligations appeared that nobody created | Extract key terms was run — it writes to the register (§6) |
| Graph edges disappeared after a re-run | Entity & concept graph replaces rather than merges (§6) |
| "Adapt to jurisdiction" cannot be found | It is not offered — see the reference |
| "monthly AI credit cap reached" | The organisation's monthly Papers AI spend cap is exhausted. It resets next month |